<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>MySQL Connector/J Developer Guide</title><link rel="stylesheet" type="text/css" href="mvl.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<script language="javascript" type="text/javascript">
  function addOnload(theFunc)
  {
    var previous = window.onload;
    if (typeof window.onload != 'function')
    {
      window.onload = theFunc;
    }
    else
    {
      window.onload = function()
      {
        previous();
        theFunc();
      }
    }
  }

  addOnload(function()
  {
    var base = new Date(1444056685*1000);
    var now = new Date();
    var diff = ((now-base)/1000)/(24*3600);

    if (diff > 90) {
      var nodes = document.getElementsByClassName('titlepage');
      nodes[0].innerHTML = '<p style="border: 5px #ff0000 solid; padding: 5px; margin 5px">' +
        'This copy of the manual is more than 90 days old. We encourage you to download a ' +
        'new version from <a href="http://dev.mysql.com">dev.mysql.com/doc</a>.</p>' + nodes[0].innerHTML;
    }
  });
</script>
<noscript></noscript>
</head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j"></a>MySQL Connector/J Developer Guide</h1></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>
        This manual describes how to install, configure, and develop
        database applications using MySQL Connector/J, the JDBC driver
        for communicating with MySQL servers.
      </p><p>
        For notes detailing the changes in each release of Connector/J,
        see <a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-j/en/" target="_top">MySQL
        Connector/J Release Notes</a>.
      </p><p>
        Document generated on:

        2015-10-05



        (revision: 44740)
      </p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#preface">Preface and Legal Notices</a></span></dt><dt><span class="chapter"><a href="#connector-j-overview">1 Overview of MySQL Connector/J</a></span></dt><dt><span class="chapter"><a href="#connector-j-versions">2 Connector/J Versions</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-change-history">2.1 Connector/J Release Notes and Change History</a></span></dt><dt><span class="section"><a href="#connector-j-versions-java">2.2 Java Versions Supported</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-installing">3 Connector/J Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-binary-installation">3.1 Installing Connector/J from a Binary Distribution</a></span></dt><dt><span class="section"><a href="#connector-j-installing-classpath">3.2 Installing the Driver and Configuring the <code class="literal">CLASSPATH</code></a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading">3.3 Upgrading from an Older Version</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-installing-upgrading-5-1">3.3.1 Upgrading to MySQL Connector/J 5.1.x</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-issues">3.3.2 JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-3-0-to-3-1">3.3.3 Upgrading from MySQL Connector/J 3.0 to 3.1</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-installing-source">3.4 Installing from the Development Source Tree</a></span></dt><dt><span class="section"><a href="#connector-j-testing">3.5 Testing Connector/J</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-examples">4 Connector/J Examples</a></span></dt><dt><span class="chapter"><a href="#connector-j-reference">5 Connector/J (JDBC) Reference</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-reference-configuration-properties">5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties
        for Connector/J</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-useconfigs">5.1.1 Properties Files for the <code class="literal">useConfigs</code> Option</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-reference-implementation-notes">5.2 JDBC API Implementation Notes</a></span></dt><dt><span class="section"><a href="#connector-j-reference-type-conversions">5.3 Java, JDBC and MySQL Types</a></span></dt><dt><span class="section"><a href="#connector-j-reference-charsets">5.4 Using Character Sets and Unicode</a></span></dt><dt><span class="section"><a href="#connector-j-reference-using-ssl">5.5 Connecting Securely Using SSL</a></span></dt><dt><span class="section"><a href="#connector-j-using-pam">5.6 Connecting Using PAM Authentication</a></span></dt><dt><span class="section"><a href="#connector-j-reference-replication-connection">5.7 Using Master/Slave Replication with ReplicationConnection</a></span></dt><dt><span class="section"><a href="#connector-j-reference-error-sqlstates">5.8 Mapping MySQL Error Numbers to JDBC SQLState Codes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-basic">6 JDBC Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-usagenotes-connect-drivermanager">6.1 Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
        Interface</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements">6.2 Using JDBC <code class="literal">Statement</code> Objects to Execute SQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements-callable">6.3 Using JDBC <code class="literal">CallableStatements</code> to Execute Stored
        Procedures</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-last-insert-id">6.4 Retrieving <code class="literal">AUTO_INCREMENT</code> Column Values through JDBC</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-j2ee-concepts-connection-pooling">7 Connection Pooling with Connector/J</a></span></dt><dt><span class="chapter"><a href="#connector-j-multi-host-connections">8 Multi-Host Connections</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-config-failover">8.1 Configuring Server Failover</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections">8.2 Configuring Load Balancing with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-master-slave-replication-connection">8.3 Configuring Master/Slave Replication with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover">8.4 Advanced Load-balancing and Failover Configuration</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-interceptors">9 Using the Connector/J Interceptor Classes</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-tomcat">10 Using Connector/J with Tomcat</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-jboss">11 Using Connector/J with JBoss</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-spring-config">12 Using Connector/J with Spring</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-jdbctemplate">12.1 Using <code class="classname">JdbcTemplate</code></a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-transactional">12.2 Transactional JDBC Access</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-connpooling">12.3 Connection Pooling with Spring</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-glassfish-config">13 Using Connector/J with GlassFish</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-jsp">13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-servlet">13.2 A Simple Servlet with GlassFish, Connector/J and MySQL</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-fabric">14 Using Connector/J with MySQL Fabric</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-troubleshooting">15 Troubleshooting Connector/J Applications</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-known-issues-limitations">16 Known Issues and Limitations</a></span></dt><dt><span class="chapter"><a href="#connector-j-support">17 Connector/J Support</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-support-community">17.1 Connector/J Community Support</a></span></dt><dt><span class="section"><a href="#connector-j-support-bug-report">17.2 How to Report Connector/J Bugs or Problems</a></span></dt></dl></dd><dt><span class="appendix"><a href="#connector-j-third-party-licenses">A Licenses for Third-Party Components</a></span></dt><dd><dl><dt><span class="section"><a href="#license-ant-contrib">A.1 Ant-Contrib License</a></span></dt><dt><span class="section"><a href="#license-c3p0-0-91">A.2 c3p0 JDBC Library License</a></span></dt><dt><span class="section"><a href="#license-gnu-lgpl-2-1">A.3 GNU Lesser General Public License Version 2.1, February 1999</a></span></dt><dt><span class="section"><a href="#license-jboss-common-jdbc-wrapper">A.4 jboss-common-jdbc-wrapper.jar License</a></span></dt><dt><span class="section"><a href="#license-nanoxml">A.5 NanoXML License</a></span></dt><dt><span class="section"><a href="#license-rox-jar">A.6 rox.jar License</a></span></dt><dt><span class="section"><a href="#license-slf4j">A.7 Simple Logging Facade for Java (SLF4J) License</a></span></dt><dt><span class="section"><a href="#license-unicode-data-files">A.8 Unicode Data Files</a></span></dt></dl></dd></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="preface"></a>Preface and Legal Notices</h1></div></div></div><p>
      This manual describes how to install, configure, and develop
      database applications using MySQL Connector/J, the JDBC driver for
      communicating with MySQL servers.
    </p><div class="simplesect"><div class="titlepage"><div><div class="simple"><h2 class="title" style="clear: both"><a name="legalnotice"></a>Legal Notices</h2></div></div></div><p>
    Copyright © 1998, 2015, Oracle and/or its affiliates. All
    rights reserved.
  </p><p>
    This software and related documentation are provided under a license
    agreement containing restrictions on use and disclosure and are
    protected by intellectual property laws. Except as expressly
    permitted in your license agreement or allowed by law, you may not
    use, copy, reproduce, translate, broadcast, modify, license,
    transmit, distribute, exhibit, perform, publish, or display any
    part, in any form, or by any means. Reverse engineering,
    disassembly, or decompilation of this software, unless required by
    law for interoperability, is prohibited.
  </p><p>
    The information contained herein is subject to change without notice
    and is not warranted to be error-free. If you find any errors,
    please report them to us in writing.
  </p><p>
    If this software or related documentation is delivered to the U.S.
    Government or anyone licensing it on behalf of the U.S. Government,
    the following notice is applicable:
  </p><p>
    U.S. GOVERNMENT RIGHTS Programs, software, databases, and related
    documentation and technical data delivered to U.S. Government
    customers are "commercial computer software" or "commercial
    technical data" pursuant to the applicable Federal Acquisition
    Regulation and agency-specific supplemental regulations. As such,
    the use, duplication, disclosure, modification, and adaptation shall
    be subject to the restrictions and license terms set forth in the
    applicable Government contract, and, to the extent applicable by the
    terms of the Government contract, the additional rights set forth in
    FAR 52.227-19, Commercial Computer Software License (December 2007).
    Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
  </p><p>
    This software is developed for general use in a variety of
    information management applications. It is not developed or intended
    for use in any inherently dangerous applications, including
    applications which may create a risk of personal injury. If you use
    this software in dangerous applications, then you shall be
    responsible to take all appropriate fail-safe, backup, redundancy,
    and other measures to ensure the safe use of this software. Oracle
    Corporation and its affiliates disclaim any liability for any
    damages caused by use of this software in dangerous applications.
  </p><p>
    Oracle is a registered trademark of Oracle Corporation and/or its
    affiliates. MySQL is a trademark of Oracle Corporation and/or its
    affiliates, and shall not be used without Oracle's express written
    authorization. Other names may be trademarks of their respective
    owners.
  </p><p>
    This software and documentation may provide access to or information
    on content, products, and services from third parties. Oracle
    Corporation and its affiliates are not responsible for and expressly
    disclaim all warranties of any kind with respect to third-party
    content, products, and services. Oracle Corporation and its
    affiliates will not be responsible for any loss, costs, or damages
    incurred due to your access to or use of third-party content,
    products, or services.
  </p><p>
    This document in any form, software or printed matter, contains
    proprietary information that is the exclusive property of Oracle.
    Your access to and use of this material is subject to the terms and
    conditions of your Oracle Software License and Service Agreement,
    which has been executed and with which you agree to comply. This
    document and information contained herein may not be disclosed,
    copied, reproduced, or distributed to anyone outside Oracle without
    prior written consent of Oracle or as specifically provided below.
    This document is not part of your license agreement nor can it be
    incorporated into any contractual agreement with Oracle or its
    subsidiaries or affiliates.
  </p><p>
    This documentation is NOT distributed under a GPL license. Use of
    this documentation is subject to the following terms:
  </p><p>
    You may create a printed copy of this documentation solely for your
    own personal use. Conversion to other formats is allowed as long as
    the actual content is not altered or edited in any way. You shall
    not publish or distribute this documentation in any form or on any
    media, except if you distribute the documentation in a manner
    similar to how Oracle disseminates it (that is, electronically for
    download on a Web site with the software) or on a CD-ROM or similar
    medium, provided however that the documentation is disseminated
    together with the software on the same medium. Any other use, such
    as any dissemination of printed copies or use of this documentation,
    in whole or in part, in another publication, requires the prior
    written consent from an authorized representative of Oracle. Oracle
    and/or its affiliates reserve any and all rights to this
    documentation not expressly granted above.
  </p><p>
    For more information on the terms of this license, or for details on
    how the MySQL documentation is built and produced, please visit
    <a class="ulink" href="http://dev.mysql.com/contact/" target="_top">MySQL Contact &amp;
    Questions</a>.
  </p><p>
    For help with using MySQL, please visit either the
    <a class="ulink" href="http://forums.mysql.com" target="_top">MySQL Forums</a> or
    <a class="ulink" href="http://lists.mysql.com" target="_top">MySQL Mailing Lists</a>
    where you can discuss your issues with other MySQL users.
  </p><p>
    For additional documentation on MySQL products, including
    translations of the documentation into other languages, and
    downloadable versions in variety of formats, including HTML and PDF
    formats, see the <a class="ulink" href="http://dev.mysql.com/doc" target="_top">MySQL
    Documentation Library</a>.
  </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-overview"></a>Chapter 1 Overview of MySQL Connector/J</h1></div></div></div><a class="indexterm" name="idm140410760846080"></a><p>
      MySQL provides connectivity for client applications developed in
      the Java programming language with MySQL Connector/J, a driver
      that implements the
      <a class="ulink" href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html" target="_top">Java
      Database Connectivity (JDBC) API</a>.
    </p><p>
      MySQL Connector/J is a JDBC Type 4 driver. Different versions are
      available that are compatible with the
      <a class="ulink" href="http://docs.oracle.com/javase/1.5.0/docs/guide/jdbc/" target="_top">JDBC
      3.0</a> and
      <a class="ulink" href="http://docs.oracle.com/javase/6/docs/technotes/guides/jdbc/" target="_top">JDBC
      4.0</a> specifications (see
      <a class="xref" href="#connector-j-versions" title="Chapter 2 Connector/J Versions">Chapter 2, <i>Connector/J Versions</i></a>). The Type 4
      designation means that the driver is a pure Java implementation of
      the MySQL protocol and does not rely on the MySQL client
      libraries.
    </p><p>
      For large-scale programs that use common design patterns of data
      access, consider using one of the popular persistence frameworks
      such as <a class="ulink" href="http://www.hibernate.org/" target="_top">Hibernate</a>,
      <a class="ulink" href="http://www.springframework.org/" target="_top">Spring's JDBC
      templates</a> or <a class="ulink" href="http://ibatis.apache.org/" target="_top">Ibatis
      SQL Maps</a> to reduce the amount of JDBC code for you to
      debug, tune, secure, and maintain.
    </p><h2><a name="idm140410760838352"></a>Key Topics</h2><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          For help with connection strings, connection options, and
          setting up your connection through JDBC, see
          <a class="xref" href="#connector-j-reference-configuration-properties" title="5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
        for Connector/J”</a>.
        </p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-versions"></a>Chapter 2 Connector/J Versions</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-change-history">2.1 Connector/J Release Notes and Change History</a></span></dt><dt><span class="section"><a href="#connector-j-versions-java">2.2 Java Versions Supported</a></span></dt></dl></div><a class="indexterm" name="idm140410760834544"></a><p>
      There are currently four versions of MySQL Connector/J available:
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Connector/J 5.1 is a Type 4 pure Java JDBC driver, which
          conforms to the JDBC 3.0 and JDBC 4.0 specifications. It
          provides compatibility with all the functionality of MySQL,
          including 4.1, 5.0, 5.1, 5.5, 5.6, and 5.7. Connector/J 5.1
          provides ease of development features, including
          auto-registration with the Driver Manager, standardized
          validity checks, categorized SQLExceptions, and support for
          the JDBC-4.0 XML processing, per connection client
          information, <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/char.html" target="_top"><code class="literal">NCHAR</code></a>,
          <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/char.html" target="_top"><code class="literal">NVARCHAR</code></a> and
          <code class="literal">NCLOB</code> types. This release also includes all
          bug fixes up to and including Connector/J 5.0.6.
        </p></li><li class="listitem"><p>
          Connector/J 5.0 provides support for all the functionality
          offered by Connector/J 3.1 and includes distributed
          transaction (XA) support.
        </p></li><li class="listitem"><p>
          Connector/J 3.1 was designed for connectivity to MySQL 4.1 and
          MySQL 5.0 servers and provides support for all the
          functionality in MySQL 5.0 except distributed transaction (XA)
          support.
        </p></li><li class="listitem"><p>
          Connector/J 3.0 provides core functionality and was designed
          for connectivity to MySQL 3.x or MySQL 4.1 servers, although
          it provides basic compatibility with later versions of MySQL.
          Connector/J 3.0 does not support server-side prepared
          statements, and does not support any of the features in
          versions of MySQL later than 4.1.
        </p></li></ul></div><p>
      The following table summarizes the Connector/J versions available,
      along with the details of JDBC driver type, what version of the
      JDBC API it supports, what versions of MySQL Server it works with,
      and whether it is currently supported or not:
    </p><p>
      </p><div class="table"><a name="idm140410765240416"></a><p class="title"><b>Table 2.1 Summary of Connector/J Versions</b></p><div class="table-contents"><table summary="Summary of Connector/J Versions" border="1"><colgroup><col><col><col><col><col></colgroup><thead><tr><th scope="col">Connector/J version</th><th scope="col">Driver Type</th><th scope="col">JDBC version</th><th scope="col">MySQL Server version</th><th scope="col">Status</th></tr></thead><tbody><tr><td scope="row">5.1</td><td>4</td><td>3.0, 4.0</td><td>4.1, 5.0, 5.1, 5.5, 5.6, 5.7</td><td>Recommended version</td></tr><tr><td scope="row">5.0</td><td>4</td><td>3.0</td><td>4.1, 5.0</td><td>Released version</td></tr><tr><td scope="row">3.1</td><td>4</td><td>3.0</td><td>4.1, 5.0</td><td>Obsolete</td></tr><tr><td scope="row">3.0</td><td>4</td><td>3.0</td><td>3.x, 4.1</td><td>Obsolete</td></tr></tbody></table></div></div><p><br class="table-break">
    </p><p>
      The current recommended version for Connector/J is 5.1. This guide
      covers all four connector versions, with specific notes given
      where a setting applies to a specific option.
    </p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-change-history"></a>2.1 Connector/J Release Notes and Change History</h2></div></div></div><p>
        For details of new features and bug fixes in each Connector/J
        release, see the
        <a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-j/en/" target="_top">MySQL
        Connector/J Release Notes</a>.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-versions-java"></a>2.2 Java Versions Supported</h2></div></div></div><p>
        The following table summarizes what version of Java RTE is
        required to use Connector/J with Java applications, and what
        version of JDK is required to build Connector/J source code:
      </p><p>
        </p><div class="table"><a name="idm140410759683808"></a><p class="title"><b>Table 2.2 Summary of Java Versions Required by Connector/J</b></p><div class="table-contents"><table summary="Summary of Java Versions Required by Connector/J" border="1"><colgroup><col><col><col></colgroup><thead><tr><th scope="col">Connector/J version</th><th scope="col">Java RTE required</th><th scope="col">JDK required (to build source code)</th></tr></thead><tbody><tr><td scope="row">5.1</td><td>1.5.x, 1.6.x, 1.7.x, 1.8.x</td><td>1.6.x and 1.5.x</td></tr><tr><td scope="row">5.0</td><td>1.3.x, 1.4.x, 1.5.x, 1.6.x</td><td>1.4.2, 1.5.x, 1.6.x</td></tr><tr><td scope="row">3.1</td><td>1.2.x, 1.3.x, 1.4.x, 1.5.x, 1.6.x</td><td>1.4.2, 1.5.x, 1.6.x</td></tr><tr><td scope="row">3.0</td><td>1.2.x, 1.3.x, 1.4.x, 1.5.x, 1.6.x</td><td>1.4.2, 1.5.x, 1.6.x</td></tr></tbody></table></div></div><p><br class="table-break">
      </p><p>
        If you are building Connector/J from source code using the
        source distribution (see
        <a class="xref" href="#connector-j-installing-source" title="3.4 Installing from the Development Source Tree">Section 3.4, “Installing from the Development Source Tree”</a>), you must use
        JDK 1.4.2 or newer to compile the package for Connector/J 5.0 or
        earlier. For Connector/J 5.1, you must have both JDK-1.6.x
        <span class="emphasis"><em>AND</em></span> JDK-1.5.x installed to be able to build
        the source code.
      </p><p>
        Java 1.7 support requires Connector/J 5.1.21 and higher.
      </p><p>
        Several JDBC 4.1 methods were implemented for the first time in
        Connector/J 5.1.21.
      </p><p>
        Because of the implementation of
        <code class="classname">java.sql.Savepoint</code>, Connector/J 3.1.0 and
        newer will not run on a Java runtime older than 1.4 unless the
        class verifier is turned off (by setting the
        <code class="option">-Xverify:none</code> option to the Java runtime). This
        is because the class verifier will try to load the class
        definition for <code class="classname">java.sql.Savepoint</code> even
        though it is not accessed by the driver unless you actually use
        savepoint functionality.
      </p><p>
        Caching functionality provided by Connector/J 3.1.0 or newer is
        also not available on JVMs older than 1.4.x, as it relies on
        <code class="classname">java.util.LinkedHashMap</code>, which was first
        available in JDK-1.4.0.
      </p><p>
        MySQL Connector/J does not support JDK-1.1.x or JDK-1.0.x.
      </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-installing"></a>Chapter 3 Connector/J Installation</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-binary-installation">3.1 Installing Connector/J from a Binary Distribution</a></span></dt><dt><span class="section"><a href="#connector-j-installing-classpath">3.2 Installing the Driver and Configuring the <code class="literal">CLASSPATH</code></a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading">3.3 Upgrading from an Older Version</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-installing-upgrading-5-1">3.3.1 Upgrading to MySQL Connector/J 5.1.x</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-issues">3.3.2 JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-3-0-to-3-1">3.3.3 Upgrading from MySQL Connector/J 3.0 to 3.1</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-installing-source">3.4 Installing from the Development Source Tree</a></span></dt><dt><span class="section"><a href="#connector-j-testing">3.5 Testing Connector/J</a></span></dt></dl></div><p>
      You can install the Connector/J package using either the binary or
      source distribution. The binary distribution provides the easiest
      method for installation; the source distribution lets you
      customize your installation further. With either solution, you
      manually add the Connector/J location to your Java
      <code class="literal">CLASSPATH</code>.
    </p><p>
      If you are upgrading from a previous version, read the upgrade
      information in <a class="xref" href="#connector-j-installing-upgrading" title="3.3 Upgrading from an Older Version">Section 3.3, “Upgrading from an Older Version”</a>
      before continuing.
    </p><p>
      Connector/J is also available as part of the Maven project. For
      more information and to download the Connector/J JAR files, see
      the
      <a class="ulink" href="http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22mysql%22%20AND%20a%3A%22mysql-connector-java%22" target="_top">Maven
      repository</a>.
    </p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-binary-installation"></a>3.1 Installing Connector/J from a Binary Distribution</h2></div></div></div><p>
        For the easiest method of installation, use the binary
        distribution of the Connector/J package. The binary distribution
        is available either as a tar/gzip or zip file. Extract it to a
        suitable location, then optionally make the information about
        the package available by changing your
        <code class="literal">CLASSPATH</code> (see
        <a class="xref" href="#connector-j-installing-classpath" title="3.2 Installing the Driver and Configuring the CLASSPATH">Section 3.2, “Installing the Driver and Configuring the <code class="literal">CLASSPATH</code>”</a>).
      </p><p>
        MySQL Connector/J is distributed as a <code class="literal">.zip</code> or
        <code class="literal">.tar.gz</code> archive containing the sources, the
        class files, and the JAR archive named
        <code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar</code>.
      </p><p>
        Starting with Connector/J 3.1.9, the <code class="filename">.class</code>
        files that constitute the JAR files are only included as part of
        the driver JAR file.
      </p><p>
        Starting with Connector/J 3.1.8, the archive also includes a
        debug build of the driver in a file named
        <code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin-g.jar</code>.
        Do not use the debug build of the driver unless instructed to do
        so when reporting a problem or a bug, as it is not designed to
        be run in production environments, and will have adverse
        performance impact when used. The debug binary also depends on
        the Aspect/J runtime library, which is located in the
        <code class="filename">src/lib/aspectjrt.jar</code> file that comes with
        the Connector/J distribution.
      </p><p>
        Use the appropriate graphical or command-line utility to extract
        the distribution (for example, WinZip for the .zip archive, and
        <span class="command"><strong>tar</strong></span> for the .tar.gz archive). Because there
        are potentially long file names in the distribution, we use the
        GNU tar archive format. Use GNU tar (or an application that
        understands the GNU tar archive format) to unpack the .tar.gz
        variant of the distribution.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-installing-classpath"></a>3.2 Installing the Driver and Configuring the <code class="literal">CLASSPATH</code></h2></div></div></div><a class="indexterm" name="idm140410759649376"></a><p>
        Once you have extracted the distribution archive, you can
        install the driver by placing
        <code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar
        </code>in your classpath, either by adding the full path to
        it to your <code class="literal">CLASSPATH</code> environment variable, or
        by directly specifying it with the command line switch
        <code class="literal">-cp</code> when starting the JVM.
      </p><p>
        To use the driver with the JDBC
        <code class="literal">DriverManager</code>, use
        <code class="literal">com.mysql.jdbc.Driver</code> as the class that
        implements <code class="classname">java.sql.Driver</code>.
      </p><p>
        You can set the <code class="literal">CLASSPATH</code> environment
        variable under Unix, Linux, or OS X either locally for a user
        within their <code class="literal">.profile</code>,
        <code class="literal">.login</code> or other login file. You can also set
        it globally by editing the global
        <code class="literal">/etc/profile</code> file.
      </p><p>
        For example, add the Connector/J driver to your
        <code class="literal">CLASSPATH</code> using one of the following forms,
        depending on your command shell:
      </p><pre class="programlisting">
# Bourne-compatible shell (sh, ksh, bash, zsh):
shell&gt; export CLASSPATH=/path/mysql-connector-java-<em class="replaceable"><code>ver</code></em>-bin.jar:$CLASSPATH

# C shell (csh, tcsh):
shell&gt; setenv CLASSPATH /path/mysql-connector-java-<em class="replaceable"><code>ver</code></em>-bin.jar:$CLASSPATH
</pre><p>
        For Windows platforms, you set the environment variable through
        the System Control Panel.
      </p><p>
        To use MySQL Connector/J with an application server such as
        GlassFish, Tomcat, or JBoss, read your vendor's documentation
        for more information on how to configure third-party class
        libraries, as most application servers ignore the
        <code class="literal">CLASSPATH</code> environment variable. For
        configuration examples for some J2EE application servers, see
        <a class="xref" href="#connector-j-usagenotes-j2ee-concepts-connection-pooling" title="Chapter 7 Connection Pooling with Connector/J">Chapter 7, <i>Connection Pooling with Connector/J</i></a>,
        <a class="xref" href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections" title="8.2 Configuring Load Balancing with Connector/J">Section 8.2, “Configuring Load Balancing with Connector/J”</a>,
        and
        <a class="xref" href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover" title="8.4 Advanced Load-balancing and Failover Configuration">Section 8.4, “Advanced Load-balancing and Failover Configuration”</a>.

        

        However, the authoritative source for JDBC connection pool
        configuration information for your particular application server
        is the documentation for that application server.
      </p><p>
        If you are developing servlets or JSPs, and your application
        server is J2EE-compliant, you can put the driver's
        <code class="literal">.jar</code> file in the
        <code class="filename">WEB-INF/lib</code> subdirectory of your webapp, as
        this is a standard location for third party class libraries in
        J2EE web applications.
      </p><p>
        You can also use the <code class="classname">MysqlDataSource</code> or
        <code class="classname">MysqlConnectionPoolDataSource</code> classes in
        the <code class="literal">com.mysql.jdbc.jdbc2.optional</code> package, if
        your J2EE application server supports or requires them. Starting
        with Connector/J 5.0.0, the
        <code class="literal">javax.sql.XADataSource</code> interface is
        implemented using the
        <code class="literal">com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</code>
        class, which supports XA distributed transactions when used in
        combination with MySQL server version 5.0 and later.
      </p><p>
        The various <code class="classname">MysqlDataSource</code> classes
        support the following parameters (through standard set
        mutators):
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">user</code>
          </p></li><li class="listitem"><p>
            <code class="literal">password</code>
          </p></li><li class="listitem"><p>
            <code class="literal">serverName</code> (see the previous section
            about failover hosts)
          </p></li><li class="listitem"><p>
            <code class="literal">databaseName</code>
          </p></li><li class="listitem"><p>
            <code class="literal">port</code>
          </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-installing-upgrading"></a>3.3 Upgrading from an Older Version</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="#connector-j-installing-upgrading-5-1">3.3.1 Upgrading to MySQL Connector/J 5.1.x</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-issues">3.3.2 JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-3-0-to-3-1">3.3.3 Upgrading from MySQL Connector/J 3.0 to 3.1</a></span></dt></dl></div><p>
        This section has information for users who are upgrading from
        one version of Connector/J to another, or to a new version of
        the MySQL server that supports a more recent level of JDBC. A
        newer version of Connector/J might include changes to support
        new features, improve existing functionality, or comply with new
        standards.
      </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-installing-upgrading-5-1"></a>3.3.1 Upgrading to MySQL Connector/J 5.1.x</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              In Connector/J 5.0.x and earlier, the alias for a table in
              a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> statement is
              returned when accessing the result set metadata using
              <code class="function">ResultSetMetaData.getColumnName()</code>.
              This behavior however is not JDBC compliant, and in
              Connector/J 5.1, this behavior has been changed so that
              the original table name, rather than the alias, is
              returned.
            </p><p>
              The JDBC-compliant behavior is designed to let API users
              reconstruct the DML statement based on the metadata within
              <code class="literal">ResultSet</code> and
              <code class="literal">ResultSetMetaData</code>.
            </p><p>
              You can get the alias for a column in a result set by
              calling
              <code class="function">ResultSetMetaData.getColumnLabel()</code>.
              To use the old noncompliant behavior with
              <code class="function">ResultSetMetaData.getColumnName()</code>,
              use the <code class="option">useOldAliasMetadataBehavior</code>
              option and set the value to <code class="literal">true</code>.
            </p><p>
              In Connector/J 5.0.x, the default value of
              <code class="option">useOldAliasMetadataBehavior</code> was
              <code class="literal">true</code>, but in Connector/J 5.1 this was
              changed to a default value of <code class="literal">false</code>.
            </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-installing-upgrading-issues"></a>3.3.2 JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</h3></div></div></div><a class="indexterm" name="idm140410759605440"></a><a class="indexterm" name="idm140410759604048"></a><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <span class="emphasis"><em>Using the UTF-8 Character Encoding</em></span> -
              Prior to MySQL server version 4.1, the UTF-8 character
              encoding was not supported by the server, however the JDBC
              driver could use it, allowing storage of multiple
              character sets in <code class="literal">latin1</code> tables on the
              server.
            </p><p>
              Starting with MySQL-4.1, this functionality is deprecated.
              If you have applications that rely on this functionality,
              and can not upgrade them to use the official Unicode
              character support in MySQL server version 4.1 or newer,
              add the following property to your connection URL:
            </p><p>
              <code class="computeroutput">useOldUTF8Behavior=true</code>
            </p></li><li class="listitem"><p>
              <span class="emphasis"><em>Server-side Prepared Statements</em></span> -
              Connector/J 3.1 will automatically detect and use
              server-side prepared statements when they are available
              (MySQL server version 4.1.0 and newer). If your
              application encounters issues with server-side prepared
              statements, you can revert to the older client-side
              emulated prepared statement code that is still presently
              used for MySQL servers older than 4.1.0 with the following
              connection property:
            </p><p>
              <code class="computeroutput">useServerPrepStmts=false</code>
            </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-installing-upgrading-3-0-to-3-1"></a>3.3.3 Upgrading from MySQL Connector/J 3.0 to 3.1</h3></div></div></div><p>
          Connector/J 3.1 is designed to be backward-compatible with
          Connector/J 3.0 as much as possible. Major changes are
          isolated to new functionality exposed in MySQL-4.1 and newer,
          which includes Unicode character sets, server-side prepared
          statements, <code class="literal">SQLState</code> codes returned in
          error messages by the server and various performance
          enhancements that can be enabled or disabled using
          configuration properties.
        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <span class="bold"><strong>Unicode Character Sets</strong></span>:
              See the next section, as well as
              <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/charset.html" target="_top">Character Set Support</a>, for information on this MySQL
              feature. If you have something misconfigured, it will
              usually show up as an error with a message similar to
              <code class="literal">Illegal mix of collations</code>.
            </p></li><li class="listitem"><p>
              <span class="bold"><strong>Server-side Prepared
              Statements</strong></span>: Connector/J 3.1 will automatically
              detect and use server-side prepared statements when they
              are available (MySQL server version 4.1.0 and newer).
            </p><p>
              Starting with version 3.1.7, the driver scans SQL you are
              preparing using all variants of
              <code class="literal">Connection.prepareStatement()</code> to
              determine if it is a supported type of statement to
              prepare on the server side, and if it is not supported by
              the server, it instead prepares it as a client-side
              emulated prepared statement. You can disable this feature
              by passing
              <code class="literal">emulateUnsupportedPstmts=false</code> in your
              JDBC URL.
            </p><p>
              If your application encounters issues with server-side
              prepared statements, you can revert to the older
              client-side emulated prepared statement code that is still
              presently used for MySQL servers older than 4.1.0 with the
              connection property
              <code class="literal">useServerPrepStmts=false</code>.
            </p></li><li class="listitem"><p>
              <span class="bold"><strong>Datetimes</strong></span> with all-zero
              components (<code class="literal">0000-00-00 ...</code>): These
              values cannot be represented reliably in Java. Connector/J
              3.0.x always converted them to <code class="literal">NULL</code>
              when being read from a ResultSet.
            </p><p>
              Connector/J 3.1 throws an exception by default when these
              values are encountered, as this is the most correct
              behavior according to the JDBC and SQL standards. This
              behavior can be modified using the
              <code class="literal">zeroDateTimeBehavior</code> configuration
              property. The permissible values are:
            </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                  <code class="literal">exception</code> (the default), which
                  throws an SQLException with an SQLState of
                  <code class="literal">S1009</code>.
                </p></li><li class="listitem"><p>
                  <code class="literal">convertToNull</code>, which returns
                  <code class="literal">NULL</code> instead of the date.
                </p></li><li class="listitem"><p>
                  <code class="literal">round</code>, which rounds the date to the
                  nearest closest value which is
                  <code class="literal">0001-01-01</code>.
                </p></li></ul></div><p>
              Starting with Connector/J 3.1.7,
              <code class="literal">ResultSet.getString()</code> can be decoupled
              from this behavior using
              <code class="literal">noDatetimeStringSync=true</code> (the default
              value is <code class="literal">false</code>) so that you can
              retrieve the unaltered all-zero value as a String. Note
              that this also precludes using any time zone conversions,
              therefore the driver will not allow you to enable
              <code class="literal">noDatetimeStringSync</code> and
              <code class="literal">useTimezone</code> at the same time.
            </p></li><li class="listitem"><p>
              <span class="bold"><strong>New SQLState Codes</strong></span>:
              Connector/J 3.1 uses SQL:1999 SQLState codes returned by
              the MySQL server (if supported), which are different from
              the legacy X/Open state codes that Connector/J 3.0 uses.
              If connected to a MySQL server older than MySQL-4.1.0 (the
              oldest version to return SQLStates as part of the error
              code), the driver will use a built-in mapping. You can
              revert to the old mapping by using the configuration
              property <code class="literal">useSqlStateCodes=false</code>.
            </p></li><li class="listitem"><p>
              <span class="bold"><strong><code class="literal">ResultSet.getString()</code></strong></span>:
              Calling <code class="literal">ResultSet.getString()</code> on a
              <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/blob.html" target="_top"><code class="literal">BLOB</code></a> column will now return
              the address of the <code class="literal">byte[]</code> array that
              represents it, instead of a <code class="literal">String</code>
              representation of the <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/blob.html" target="_top"><code class="literal">BLOB</code></a>.
              <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/blob.html" target="_top"><code class="literal">BLOB</code></a> values have no
              character set, so they cannot be converted to
              <code class="literal">java.lang.String</code>s without data loss or
              corruption.
            </p><p>
              To store strings in MySQL with LOB behavior, use one of
              the <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/blob.html" target="_top"><code class="literal">TEXT</code></a> types, which the
              driver will treat as a <code class="literal">java.sql.Clob</code>.
            </p></li><li class="listitem"><p>
              <span class="bold"><strong>Debug builds</strong></span>: Starting
              with Connector/J 3.1.8 a debug build of the driver in a
              file named
              <code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin-g.jar</code>
              is shipped alongside the normal binary jar file that is
              named
              <code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar</code>.
            </p><p>
              Starting with Connector/J 3.1.9, we do not ship the
              <code class="literal">.class</code> files unbundled, they are only
              available in the JAR archives that ship with the driver.
            </p><p>
              Do not use the debug build of the driver unless instructed
              to do so when reporting a problem or bug, as it is not
              designed to be run in production environments, and will
              have adverse performance impact when used. The debug
              binary also depends on the Aspect/J runtime library, which
              is located in the
              <code class="filename">src/lib/aspectjrt.jar</code> file that comes
              with the Connector/J distribution.
            </p></li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-installing-source"></a>3.4 Installing from the Development Source Tree</h2></div></div></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Caution</div><p>
          Read this section only if you are interested in helping us
          test our new code. To just get MySQL Connector/J up and
          running on your system, use a standard binary release
          distribution.
        </p></div><p>
        The requirements and steps for installing Connector/J
        <a class="link" href="#connector-j-installing-5.1.34" title="Installing Connector/J 5.1.34 or later from the development source tree">5.1.34 or
        later</a> and
        <a class="link" href="#connector-j-installing-5.1.33" title="Installing Connector/J 5.1.33 or earlier from the development source tree">5.1.33 or
        earlier</a> from source are different; check the section
        below that is relevant for the version you want.
      </p><p><a name="connector-j-installing-5.1.34"></a><b>Installing Connector/J 5.1.34 or later from the development source tree. </b>
          To install MySQL Connector/J from the development source tree,
          make sure that you have the following software on your system:
        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A Git client, to check out the sources from our GitHub
            repository (available from
            <a class="ulink" href="http://git-scm.com/downloads" target="_top">http://git-scm.com/downloads</a>).
          </p></li><li class="listitem"><p>
            Apache Ant version 1.8.2 or newer (available from
            <a class="ulink" href="http://ant.apache.org/" target="_top">http://ant.apache.org/</a>).
          </p></li><li class="listitem"><p>
            JDK 1.6.x <span class="emphasis"><em>AND</em></span> JDK 1.5.x.
          </p></li><li class="listitem"><p>
            JUnit libraries (available from
            <a class="ulink" href="https://github.com/junit-team/junit/wiki/Download-and-Install" target="_top">https://github.com/junit-team/junit/wiki/Download-and-Install</a>).
          </p></li><li class="listitem"><p>
            The required <code class="filename">.jar</code> files from the
            Hibernate ORM 4.1 or 4.2 Final release bundle, which is
            available at
            <a class="ulink" href="http://sourceforge.net/projects/hibernate/files/hibernate4/" target="_top">http://sourceforge.net/projects/hibernate/files/hibernate4/</a>.
          </p></li></ul></div><p>
        To check out and compile MySQL Connector/J, follow these steps:
      </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
            Check out the code from the source code repository for MySQL
            Connector/J located on GitHub at
            <a class="ulink" href="https://github.com/mysql/mysql-connector-j" target="_top">https://github.com/mysql/mysql-connector-j</a>;
            for the latest release of the Connector/J 5.1 series, use
            the following command:
          </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>git clone https://github.com/mysql/mysql-connector-j.git </code></strong>
</pre><p>
            To check out a release other than the latest one, use the
            <code class="option">--branch</code> option to specify the revision tag
            for it:

</p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>git clone --branch 5.1.<em class="replaceable"><code>xx</code></em> https://github.com/mysql/mysql-connector-j.git </code></strong>
</pre><p>
          </p><p>
            Under the current directory, the commands create a
            <code class="filename">mysql-connector-j</code> subdirectory , which
            contains the code you want.
          </p></li><li class="listitem"><p>
            Make sure that you have both JDK 1.6.x
            <span class="emphasis"><em>AND</em></span> JDK 1.5.x installed. You need both
            JDKs because Connector/J 5.1 supports both JDBC 3.0 (which
            has existed prior to JDK 1.6.x) and JDBC 4.0.
          </p></li><li class="listitem"><p>
            Place the required <code class="filename">junit.jar</code> file in a
            separate directory—for example,
            <code class="filename">/home/username/ant-extralibs</code>.
          </p></li><li class="listitem"><p>
            In the same directory for extra libraries described in the
            last step, create a directory named
            <code class="filename">hibernate4</code>, and put under it all the
            <code class="filename">.jar</code> files you can find under the
            <code class="filename">/lib/required/</code> folder in the Hibernate
            ORM 4 Final release bundle.
          </p></li><li class="listitem"><p>
            Change your current working directory to the
            <code class="filename">mysql-connector-j</code> directory created in
            step 1 above.
          </p></li><li class="listitem"><p>
            In the directory, create a file named
            <code class="filename">build.properties</code> to indicate to Ant the
            locations of the root directories for your JDK 1.5.x and JDK
            1.6.x installations, as well as the location of the extra
            libraries. The file should contain the following property
            settings, with the
            <span class="quote">“<span class="quote"><em class="replaceable"><code>path_to_*</code></em></span>”</span> parts
            replaced by the appropriate filepaths:
          </p><pre class="programlisting">
com.mysql.jdbc.jdk5=<em class="replaceable"><code>path_to_jdk_1.5</code></em>
com.mysql.jdbc.jdk6=<em class="replaceable"><code>path_to_jdk_1.6</code></em>
com.mysql.jdbc.extra.libs=<em class="replaceable"><code>path_to_folder_for_extra_libraries</code></em> 
</pre><p>
            Alternatively, you can set the values of those properties
            through the Ant <code class="option">-D</code> options.
          </p></li><li class="listitem"><p>
            Issue the following command to compile the driver and create
            a <code class="filename">.jar</code> file for Connector/J:
          </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>ant dist</code></strong>
</pre><p>
            This creates a <code class="filename">build</code> directory in the
            current directory, where all the build output goes. A
            directory is created under the <code class="filename">build</code>
            directory, whose name includes the version number of the
            release you are building. That directory contains the
            sources, the compiled <code class="filename">.class</code> files, and
            a <code class="filename">.jar</code> file for deployment. For more
            information and other possible targets, including those that
            create a fully packaged distribution, issue the following
            command:
          </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>ant -projecthelp</code></strong>
</pre></li><li class="listitem"><p>
            Install the newly created <code class="filename">.jar</code> file for
            the JDBC driver as you would install a binary
            <code class="filename">.jar</code> file you download from MySQL by
            following the instructions given in
            <a class="xref" href="#connector-j-installing-classpath" title="3.2 Installing the Driver and Configuring the CLASSPATH">Section 3.2, “Installing the Driver and Configuring the <code class="literal">CLASSPATH</code>”</a>.
          </p></li></ol></div><p>
        Note that a package containing both the binary and source code
        for Connector/J 5.1 can also be found at
        <a class="ulink" href="http://dev.mysql.com/downloads/connector/j/5.1.html" target="_top">
        Connector/J 5.1 Download</a>
      </p><p><a name="connector-j-installing-5.1.33"></a><b>Installing Connector/J 5.1.33 or earlier from the development source
          tree. </b>
          To install MySQL Connector/J 5.1.33 or earlier from the
          development source tree, make sure that you have the following
          software on your system:
        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A Git client, to check out the source code from our GitHub
            repository (available from
            <a class="ulink" href="http://git-scm.com/downloads" target="_top">http://git-scm.com/downloads</a>).
          </p></li><li class="listitem"><p>
            Apache Ant version 1.7 or newer (available from
            <a class="ulink" href="http://ant.apache.org/" target="_top">http://ant.apache.org/</a>).
          </p></li><li class="listitem"><p>
            JDK 1.6.x <span class="emphasis"><em>AND</em></span> JDK 1.5.x. Refer to
            <a class="xref" href="#connector-j-versions-java" title="2.2 Java Versions Supported">Section 2.2, “Java Versions Supported”</a> for the version
            of Java you need to build or run any Connector/J release.
          </p></li><li class="listitem"><p>
            The Ant Contrib (version 1.03b is available from
            <a class="ulink" href="http://sourceforge.net/projects/ant-contrib/files/ant-contrib/1.0b3/" target="_top">http://sourceforge.net/projects/ant-contrib/files/ant-contrib/1.0b3/</a>)
            and JUnit (available from
            <a class="ulink" href="https://github.com/junit-team/junit/wiki/Download-and-Install" target="_top">https://github.com/junit-team/junit/wiki/Download-and-Install</a>)
            libraries.
          </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The required <code class="filename">.jar</code> files from the
            Hibernate ORM 4.1 or 4.2 Final release bundle, which is
            available at
            <a class="ulink" href="http://sourceforge.net/projects/hibernate/files/hibernate4/" target="_top">http://sourceforge.net/projects/hibernate/files/hibernate4/</a>.
          </p></li></ul></div><p>
        To check out and compile a specific branch of MySQL Connector/J,
        follow these steps:
      </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
            Check out the code from the source code repository for MySQL
            Connector/J located on GitHub at
            <a class="ulink" href="https://github.com/mysql/mysql-connector-j" target="_top">https://github.com/mysql/mysql-connector-j</a>,
            using the <code class="option">--branch</code> option to specify the
            revision tag for release 5.1.<em class="replaceable"><code>xx</code></em>:

</p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>git clone --branch 5.1.<em class="replaceable"><code>xx</code></em> https://github.com/mysql/mysql-connector-j.git </code></strong>
</pre><p>
          </p><p>
            Under the current directory, the commands create a
            <code class="filename">mysql-connector-j</code> subdirectory , which
            contains the code you want.
          </p></li><li class="listitem"><p>
            To build Connector/J 5.1, make sure that you have both JDK
            1.6.x <span class="emphasis"><em>AND</em></span> JDK 1.5.x installed. You need
            both JDKs because Connector/J 5.1 supports both JDBC 3.0
            (which has existed prior to JDK 1.6.x) and JDBC 4.0. Set
            your <code class="literal">JAVA_HOME</code> environment variable to
            the path to the JDK 1.5.x installation.
          </p></li><li class="listitem"><p>
            Place the required <code class="filename">ant-contrib.jar</code> file
            (in exactly that name, without the version number in it;
            rename the <code class="filename">jar</code> file if needed) and
            <code class="filename">junit.jar</code> file in a separate
            directory—for example,
            <code class="filename">/home/username/ant-extralibs</code>.
          </p></li><li class="listitem"><p>
            In the same directory for extra libraries described in the
            last step, create a directory named
            <code class="filename">hibernate4</code>, and put under it all the
            <code class="filename">.jar</code> files you can find under the
            <code class="filename">/lib/required/</code> folder in the Hibernate
            ORM 4 Final release bundle.
          </p></li><li class="listitem"><p>
            Change your current working directory to the
            <code class="filename">mysql-connector-j</code> directory created in
            step 1 above.
          </p></li><li class="listitem"><p>
            In the directory, create a file named
            <code class="filename">build.properties</code> to indicate to Ant the
            locations of the Javac and <code class="filename">rt.jar</code> of
            your JDK 1.6.x, as well as the location of the extra
            libraries. The file should contain the following property
            settings, with the
            <span class="quote">“<span class="quote"><em class="replaceable"><code>path_to_*</code></em></span>”</span> parts
            replaced by the appropriate filepaths:
          </p><pre class="programlisting">
com.mysql.jdbc.java6.javac=<em class="replaceable"><code>path_to_javac_1.6</code></em>/javac
com.mysql.jdbc.java6.rtjar=<em class="replaceable"><code>path_to_rt.jar_under_jdk_1.6</code></em>/rt.jar
com.mysql.jdbc.extra.libs=<em class="replaceable"><code>path_to_folder_for_extra_libraries</code></em>
</pre><p>
            Alternatively, you can set the values of those properties
            through the Ant <code class="option">-D</code> options.
          </p></li><li class="listitem"><p>
            Issue the following command to compile the driver and create
            a <code class="filename">.jar</code> file for Connector/J:
          </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>ant dist</code></strong>
</pre><p>
            This creates a <code class="filename">build</code> directory in the
            current directory, where all the build output goes. A
            directory is created under the <code class="filename">build</code>
            directory, whose name includes the version number of the
            release you are building. That directory contains the
            sources, the compiled <code class="filename">.class</code> files, and
            a <code class="filename">.jar</code> file for deployment. For more
            information and other possible targets, including those that
            create a fully packaged distribution, issue the following
            command:
          </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>ant -projecthelp</code></strong>
</pre></li><li class="listitem"><p>
            Install the newly created <code class="filename">.jar</code> file for
            the JDBC driver as you would install a binary
            <code class="filename">.jar</code> file you download from MySQL by
            following the instructions given in
            <a class="xref" href="#connector-j-installing-classpath" title="3.2 Installing the Driver and Configuring the CLASSPATH">Section 3.2, “Installing the Driver and Configuring the <code class="literal">CLASSPATH</code>”</a>.
          </p></li></ol></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-testing"></a>3.5 Testing Connector/J</h2></div></div></div><p>
        The Connector/J source code repository or packages that are
        shipped with source code include an extensive test suite,
        containing test cases that can be executed independently. The
        test cases are divided into the following categories:

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <span class="emphasis"><em>Functional or unit tests:</em></span> Classes
              from the package <code class="classname">testsuite.simple</code>.
              Include test code for the main features of the
              Connector/J.
            </p></li><li class="listitem"><p>
              <span class="emphasis"><em>Performance tests:</em></span> Classes from the
              package <code class="classname">testsuite.perf</code>. Include
              test code to make measurements for the performance of
              Connector/J.
            </p></li><li class="listitem"><p>
              <span class="emphasis"><em>Fabric tests:</em></span> Classes from the
              package <code class="classname">testsuite.fabric</code>. Includes
              the code to test Fabric-specific features. These tests
              require the setting of some special properties that are
              not documented here. Consult the code or the
              Fabric-related targets in the bundled Ant build file,
              <code class="filename">build.xml</code>.
            </p></li><li class="listitem"><p>
              <span class="emphasis"><em>Regression tests:</em></span> Classes from the
              package <code class="classname">testsuite.regression</code>.
              Includes code for testing bug and regression fixes.
            </p></li></ul></div><p>
      </p><p>
        The bundled Ant build file contains targets like
        <code class="literal">test</code> and <code class="literal">test-multijvm</code>,
        which can facilitate the process of running the Connector/J
        tests; see the target descriptions in the build file for
        details. Besides the requirements for building Connector/J from
        the source code described in
        <a class="xref" href="#connector-j-installing-source" title="3.4 Installing from the Development Source Tree">Section 3.4, “Installing from the Development Source Tree”</a>, a number of the
        tests also require the File System Service Provider 1.2 for the
        Java Naming and Directory Interface (JNDI), available at
        <a class="ulink" href="http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html" target="_top">http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html</a>)—place
        the jar files downloaded from there into the
        <code class="filename">lib</code> directory or in the directory pointed
        to by the property <code class="literal">com.mysql.jdbc.extra.libs</code>.
      </p><p>
        To run the test using Ant, in addition to the properties
        required for <a class="xref" href="#connector-j-installing-source" title="3.4 Installing from the Development Source Tree">Section 3.4, “Installing from the Development Source Tree”</a>,
        you must set the following properties in the
        <code class="filename">build.properties</code> file or through the Ant
        <code class="option">-D</code> options:

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">com.mysql.jdbc.testsuite.url</code>: it
              specifies the JDBC URL for connection to a MySQL test
              server; see
              <a class="xref" href="#connector-j-reference-configuration-properties" title="5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
        for Connector/J”</a>.
            </p></li><li class="listitem"><p>
              <code class="literal">com.mysql.jdbc.testsuite.jvm</code>: the JVM
              to be used for the tests. If the property is set, the
              specified JVM will be used for all test cases except if it
              points to a Java 5 directory, in which case any test cases
              for JDBC 4.0 and later are run with the JVM supplied with
              the property <code class="literal">com.mysql.jdbc.jdk6</code>. If
              the property is not set, the JVM supplied with
              <code class="literal">com.mysql.jdbc.jdk5</code> will be used to run
              test cases for JDBC 3.0 and the one supplied with
              <code class="literal">com.mysql.jdbc.jdk6</code> will be used to run
              test cases for JDBC 4.0 and later.
            </p></li></ul></div><p>
      </p><p>
        After setting these parameters, run the tests with Ant in the
        following ways:

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Building the <code class="literal">test</code> target with
              <code class="literal">ant test</code> runs all test cases by default
              on a single server instance. If you want to run a
              particular test case, put the test's fully qualified class
              names in the <code class="literal">test</code> variable; for
              example:

</p><pre class="programlisting">
shell &gt; <strong class="userinput"><code>ant -Dtest=testsuite.simple.StringUtilsTest test</code></strong></pre><p>

              You can also run individual tests in a test case by
              specifying the names of the corresponding methods in the
              <code class="literal">methods</code> variable, separating multiple
              methods by commas; for example:

</p><pre class="programlisting">
shell &gt; <strong class="userinput"><code>ant -Dtest=testsuite.simple.StringUtilsTest -Dmethods=testIndexOfIgnoreCase,testGetBytes test</code></strong>
</pre><p>
            </p></li><li class="listitem"><p>
              Building the <code class="literal">test-multijvm</code> target with
              <code class="literal">ant test-multijvm</code> runs all the test
              cases


              using multiple JVMs of different versions on multiple
              server instances. For example, if you want to run the
              tests using a Java 7 and a Java 8 JVM on three server
              instances with different configurations, you will need to
              use the following properties:

</p><pre class="programlisting">
com.mysql.jdbc.testsuite.jvm.1=<strong class="userinput"><code>path_to_Java_7</code></strong>
com.mysql.jdbc.testsuite.jvm.2=<strong class="userinput"><code>path_to_Java_8</code></strong>
com.mysql.jdbc.testsuite.url.1=<strong class="userinput"><code>URL_to_1st_server</code></strong>
com.mysql.jdbc.testsuite.url.2=<strong class="userinput"><code>URL_to_2nd_server</code></strong> 
com.mysql.jdbc.testsuite.url.3=<strong class="userinput"><code>URL_to_3rd_server</code></strong></pre><p>
            </p><p>
              Unlike the target <code class="literal">test</code>, the target
              <code class="literal">test-multijvm</code> only recognizes the
              properties
              <code class="literal">com.mysql.jdbc.testsuite.jvm.<strong class="userinput"><code>N</code></strong></code>
              and
              <code class="literal">com.mysql.jdbc.testsuite.url.<strong class="userinput"><code>N</code></strong></code>,
              where <strong class="userinput"><code>N</code></strong> is a numeric suffice; the
              same properties without the suffices are ignored by
              <code class="literal">test-multijvm</code>. As with the target
              <code class="literal">test</code>, if any of the
              <code class="literal">com.mysql.jdbc.testsuite.jvm.<strong class="userinput"><code>N</code></strong></code>
              settings points to Java 5, then Ant relies on the property
              <code class="literal">com.mysql.jdbc.jdk6</code> to run the tests
              specific to JDBC 4.0 and later.
            </p><p>
              You can choose to run individual test cases or specific
              tests by using the <code class="literal">test</code> or
              <code class="literal">methods</code> property, as explained in the
              last bullet for the target <code class="literal">test</code>. Each
              test is run once per possible combination of JVMs and
              server instances (that is, 6 times in total for in this
              example).
            </p><p>
              When a test for a certain JVM-server combination has
              failed, <code class="literal">test-multijvm</code> does not throw an
              error, but moves on to the next combination, until all
              tests for all combinations are finished.
            </p></li></ul></div><p>
      </p><p>
        While the test results are partially reported by the console,
        complete reports in HTML and XML formats are provided:

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              For results of <code class="literal">test</code>: view the HTML
              report by opening
              <code class="filename">build/junit/unitregress/report/index.html</code>.
              XML version of the reports are located in the folder
              <code class="filename">build/junit/unitregress</code>.
            </p></li><li class="listitem"><p>
              For results of <code class="literal">test-multijvm</code>: view the
              HTML report for each JVM-server combination by opening
              <code class="filename">build/junit/MySQL<em class="replaceable"><code>N</code></em>.<em class="replaceable"><code>server_version</code></em>/<em class="replaceable"><code>operating_system_version</code></em>/<em class="replaceable"><code>jvm-version</code></em>/unitregress/report/index.html</code>.
              XML version of the reports are located in the folder
              <code class="filename">build/junit/MySQL<em class="replaceable"><code>N</code></em>.<em class="replaceable"><code>server_version</code></em>/<em class="replaceable"><code>operating_system_version</code></em>/<em class="replaceable"><code>jvm-version</code></em>/unitregress</code>.
            </p></li></ul></div><p>
      </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-examples"></a>Chapter 4 Connector/J Examples</h1></div></div></div><a class="indexterm" name="idm140410759401936"></a><p>
      Examples of using Connector/J are located throughout this
      document. This section provides a summary and links to these
      examples.
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-connection-drivermanager" title="Example 6.1 Connector/J: Obtaining a connection from the DriverManager">Example 6.1, “Connector/J: Obtaining a connection from the
          <code class="literal">DriverManager</code>”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-execute-select" title="Example 6.2 Connector/J: Using java.sql.Statement to execute a SELECT query">Example 6.2, “Connector/J: Using java.sql.Statement to execute a
          <code class="literal">SELECT</code> query”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-stored-procedure" title="Example 6.3 Connector/J: Calling Stored Procedures">Example 6.3, “Connector/J: Calling Stored Procedures”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-preparecall" title="Example 6.4 Connector/J: Using Connection.prepareCall()">Example 6.4, “Connector/J: Using <code class="literal">Connection.prepareCall()</code>”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-output-param" title="Example 6.5 Connector/J: Registering output parameters">Example 6.5, “Connector/J: Registering output parameters”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-callablestatement" title="Example 6.6 Connector/J: Setting CallableStatement input parameters">Example 6.6, “Connector/J: Setting <code class="literal">CallableStatement</code> input
                parameters”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-retrieving-results-params" title="Example 6.7 Connector/J: Retrieving results and output parameter values">Example 6.7, “Connector/J: Retrieving results and output parameter values”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-autoincrement-getgeneratedkeys" title="Example 6.8 Connector/J: Retrieving AUTO_INCREMENT column values using Statement.getGeneratedKeys()">Example 6.8, “Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
          using <code class="literal">Statement.getGeneratedKeys()</code>”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-autoincrement-select" title="Example 6.9 Connector/J: Retrieving AUTO_INCREMENT column values using SELECT LAST_INSERT_ID()">Example 6.9, “Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
          using <code class="literal">SELECT LAST_INSERT_ID()</code>”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-autoincrement-updateable-resultsets" title="Example 6.10 Connector/J: Retrieving AUTO_INCREMENT column values in Updatable ResultSets">Example 6.10, “Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
          in <code class="literal">Updatable ResultSets</code>”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-connectionpool-j2ee" title="Example 7.1 Connector/J: Using a connection pool with a J2EE application server">Example 7.1, “Connector/J: Using a connection pool with a J2EE application server”</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="#connector-j-examples-transaction-retry" title="Example 15.1 Connector/J: Example of transaction with retry logic">Example 15.1, “Connector/J: Example of transaction with retry logic”</a>
        </p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-reference"></a>Chapter 5 Connector/J (JDBC) Reference</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-reference-configuration-properties">5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties
        for Connector/J</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-useconfigs">5.1.1 Properties Files for the <code class="literal">useConfigs</code> Option</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-reference-implementation-notes">5.2 JDBC API Implementation Notes</a></span></dt><dt><span class="section"><a href="#connector-j-reference-type-conversions">5.3 Java, JDBC and MySQL Types</a></span></dt><dt><span class="section"><a href="#connector-j-reference-charsets">5.4 Using Character Sets and Unicode</a></span></dt><dt><span class="section"><a href="#connector-j-reference-using-ssl">5.5 Connecting Securely Using SSL</a></span></dt><dt><span class="section"><a href="#connector-j-using-pam">5.6 Connecting Using PAM Authentication</a></span></dt><dt><span class="section"><a href="#connector-j-reference-replication-connection">5.7 Using Master/Slave Replication with ReplicationConnection</a></span></dt><dt><span class="section"><a href="#connector-j-reference-error-sqlstates">5.8 Mapping MySQL Error Numbers to JDBC SQLState Codes</a></span></dt></dl></div><p>
      This section of the manual contains reference material for MySQL
      Connector/J.
    </p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-configuration-properties"></a>5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties
        for Connector/J</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="#connector-j-useconfigs">5.1.1 Properties Files for the <code class="literal">useConfigs</code> Option</a></span></dt></dl></div><a class="indexterm" name="idm140410759381696"></a><a class="indexterm" name="idm140410759380304"></a><p>
        The name of the class that implements
        <code class="literal">java.sql.Driver</code> in MySQL Connector/J is
        <code class="literal">com.mysql.jdbc.Driver</code>. The
        <code class="literal">org.gjt.mm.mysql.Driver</code> class name is also
        usable for backward compatibility with MM.MySQL, the predecessor
        of Connector/J. Use this class name when registering the driver,
        or when configuring a software to use MySQL Connector/J.
      </p><h3><a name="connector-j-reference-url-format"></a>JDBC URL Format</h3><p>
        The general format for a JDBC URL for connecting to a MySQL
        server is as follows, with items in square brackets ([ ]) being
        optional:
      </p><pre class="programlisting">
jdbc:mysql://[<em class="replaceable"><code>host1</code></em>][:<em class="replaceable"><code>port1</code></em>][,[<em class="replaceable"><code>host2</code></em>][:<em class="replaceable"><code>port2</code></em>]]...[/[<em class="replaceable"><code>database</code></em>]] »
[?<em class="replaceable"><code>propertyName1</code></em>=<em class="replaceable"><code>propertyValue1</code></em>[&amp;<em class="replaceable"><code>propertyName2</code></em>=<em class="replaceable"><code>propertyValue2</code></em>]...]
</pre><p>
        Here is a simple example for a connection URL:
      </p><pre class="programlisting">
jdbc:mysql://localhost:3306/sakila?profileSQL=true
</pre><p>
        Supply multiple hosts for a server failover setup (see
        <a class="xref" href="#connector-j-multi-host-connections" title="Chapter 8 Multi-Host Connections">Chapter 8, <i>Multi-Host Connections</i></a> for
        details):
      </p><pre class="programlisting">
# Connection URL for a server failover setup: 
jdbc:mysql//primaryhost,secondaryhost1,secondaryhost2/test</pre><p>
        There are specialized URL schemes for configuring Connector/J's
        multi-host functions like load balancing and replication; here
        are some examples (see
        <a class="xref" href="#connector-j-multi-host-connections" title="Chapter 8 Multi-Host Connections">Chapter 8, <i>Multi-Host Connections</i></a> for
        details):

</p><pre class="programlisting">
# Connection URL for load balancing: 
jdbc:mysql:loadbalance://localhost:3306,localhost:3310/sakila

# Connection URL for server replication: 
jdbc:mysql:replication://master,slave1,slave2,slave3/test
</pre><p>
      </p><h3><a name="idm140410759366240"></a>Host and Port</h3><p>
        If no hosts are not specified, the host name defaults to
        <code class="literal">127.0.0.1</code>. If the port for a host is not
        specified, it defaults to <code class="literal">3306</code>, the default
        port number for MySQL servers.
      </p><h3><a name="idm140410759363728"></a>Initial Database for Connection</h3><p>
        If the database is not specified, the connection is made with no
        default database. In this case, either call the
        <code class="function">setCatalog()</code> method on the Connection
        instance, or fully specify table names using the database name
        (that is, <code class="literal">SELECT
        <em class="replaceable"><code>dbname</code></em>.<em class="replaceable"><code>tablename</code></em>.<em class="replaceable"><code>colname</code></em>
        FROM dbname.tablename...</code>) in your SQL. Opening a
        connection without specifying the database to use is generally
        only useful when building tools that work with multiple
        databases, such as GUI database managers.
      </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
          Always use the <code class="literal">Connection.setCatalog()</code>
          method to specify the desired database in JDBC applications,
          rather than the <code class="literal">USE
          <em class="replaceable"><code>database</code></em></code> statement.
        </p></div><h3><a name="connector-j-reference-ipv6-url"></a>IPv6 Connections</h3><a class="indexterm" name="idm140410759356544"></a><p>
        For IPv6 connections, use this alternative syntax to specify
        hosts in the URL (the same syntax can also be used for IPv4
        connections):

</p><pre class="programlisting">
jdbc:mysql://address=(<em class="replaceable"><code>key1</code></em>=<em class="replaceable"><code>value</code></em>)[(<em class="replaceable"><code>key2</code></em>=<em class="replaceable"><code>value</code></em>)]...[,address=(key3=value)[(key4=value)]...]...[/[<em class="replaceable"><code>database</code></em>]]»
[?<em class="replaceable"><code>propertyName1</code></em>=<em class="replaceable"><code>propertyValue1</code></em>[&amp;<em class="replaceable"><code>propertyName2</code></em>=<em class="replaceable"><code>propertyValue2</code></em>]...] 
</pre><p>

        Supported keys include:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">(protocol=tcp)</code>, or
            <code class="literal">(protocol=pipe)</code> for named pipes on
            Windows.
          </p></li><li class="listitem"><p>
            <code class="literal">(path=<em class="replaceable"><code>path_to_pipe</code></em>)</code>
            for named pipes.
          </p></li><li class="listitem"><p>
            <code class="literal">(host=<em class="replaceable"><code>hostname</code></em>)</code>
            for TCP connections.
          </p></li><li class="listitem"><p>
            <code class="literal">(port=<em class="replaceable"><code>port_number</code></em>)</code>
            for TCP connections.
          </p></li></ul></div><p>
        For example:
      </p><pre class="programlisting">
jdbc:mysql://address=(protocol=tcp)(host=localhost)(port=3306)/db 
</pre><p>
        Keys other than the four mentioned above are treated as
        host-specific configuration properties, which allow per-host
        overrides of any configuration property set for multi-host
        connections (that is, when using failover, load balancing, or
        replication). For example:

</p><pre class="programlisting">
# IPv6 Connection URL for a server failover setup: 
jdbc:mysql//address=(protocol=tcp)(host=primaryhost)(port=3306),»
address=(protocol=tcp)(host=secondaryhost1)(port=3310)(user=test2)/test

# IPv6 Connection URL for load balancing: 
jdbc:mysql:loadbalance://address=(protocol=tcp)(host=localhost)(port=3306)(user=test1),»
address=(protocol=tcp)(host=localhost)(port=3310)(user=test2)/sakila

# IPv6 Connection URL for server replication: 
jdbc:mysql:replication://address=(protocol=tcp)(host=master)(port=3306)(user=test1),»
address=(protocol=tcp)(host=slave1)(port=3310)(user=test2)/test
</pre><p>

        Limit the overrides to user, password, network timeouts, and
        statement and metadata cache sizes; the effects of other
        per-host overrides are not defined.
      </p><p>
        The ways to set the other configuration properties are the same
        for IPv6 and IPv4 URLs; see
        <a class="xref" href="#connector-j-reference-set-config" title="Setting Configuration Properties">Setting Configuration Properties</a>.
      </p><p></p><h3><a name="connector-j-reference-set-config"></a>Setting Configuration Properties</h3><p>
        Configuration properties define how Connector/J will make a
        connection to a MySQL server. Unless otherwise noted, properties
        can be set for a <code class="literal">DataSource</code> object or for a
        <code class="literal">Connection</code> object.
      </p><p>
        Configuration properties can be set in one of the following
        ways:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Using the <code class="literal">set*()</code> methods on MySQL
            implementations of <code class="literal">java.sql.DataSource</code>
            (which is the preferred method when using implementations of
            <code class="literal">java.sql.DataSource</code>):
          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">com.mysql.jdbc.jdbc2.optional.MysqlDataSource</code>
              </p></li><li class="listitem"><p>
                <code class="literal">com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource</code>
              </p></li></ul></div></li><li class="listitem"><p>
            As a key/value pair in the
            <code class="literal">java.util.Properties</code> instance passed to
            <code class="literal">DriverManager.getConnection()</code> or
            <code class="literal">Driver.connect()</code>
          </p></li><li class="listitem"><p>
            As a JDBC URL parameter in the URL given to
            <code class="literal">java.sql.DriverManager.getConnection()</code>,
            <code class="literal">java.sql.Driver.connect()</code> or the MySQL
            implementations of the
            <code class="literal">javax.sql.DataSource</code>
            <code class="function">setURL()</code> method. If you specify a
            configuration property in the URL without providing a value
            for it, nothing will be set; for example, adding
            <code class="literal">useServerPrepStmts</code> alone to the URL does
            not make Connector/J use server-side prepared statements;
            you need to add <code class="literal">useServerPrepStmts=true</code>.
          </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
              If the mechanism you use to configure a JDBC URL is
              XML-based, use the XML character literal
              <code class="literal">&amp;amp;</code> to separate configuration
              parameters, as the ampersand is a reserved character for
              XML.
            </p></div></li></ul></div><p>
        The properties are listed in the following tables.
      </p><p><b>Connection/Authentication. </b>
      </p><div class="informaltable"><table summary="This table lists Connector/J Connection/Authentication
          connection properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
                  <span class="strong"><strong>user</strong></span>
                </p>



                <p>
                  The user to connect as
                </p>



                <p>
                  Since version: all versions
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>password</strong></span>
                </p>



                <p>
                  The password to use when connecting
                </p>



                <p>
                  Since version: all versions
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>socketFactory</strong></span>
                </p>



                <p>
                  The name of the class that the driver should use for
                  creating socket connections to the server. This class
                  must implement the interface
                  'com.mysql.jdbc.SocketFactory' and have public no-args
                  constructor.
                </p>



                <p>
                  Default: com.mysql.jdbc.StandardSocketFactory
                </p>



                <p>
                  Since version: 3.0.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>connectTimeout</strong></span>
                </p>



                <p>
                  Timeout for socket connect (in milliseconds), with 0
                  being no timeout. Only works on JDK-1.4 or newer.
                  Defaults to '0'.
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 3.0.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>socketTimeout</strong></span>
                </p>



                <p>
                  Timeout on network socket operations (0, the default
                  means no timeout).
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 3.0.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>connectionLifecycleInterceptors</strong></span>
                </p>



                <p>
                  A comma-delimited list of classes that implement
                  "com.mysql.jdbc.ConnectionLifecycleInterceptor" that
                  should notified of connection lifecycle events
                  (creation, destruction, commit, rollback, setCatalog
                  and setAutoCommit) and potentially alter the execution
                  of these commands. ConnectionLifecycleInterceptors are
                  "stackable", more than one interceptor may be
                  specified via the configuration property as a
                  comma-delimited list, with the interceptors executed
                  in order from left to right.
                </p>



                <p>
                  Since version: 5.1.4
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useConfigs</strong></span>
                </p>



                <p>
                  Load the comma-delimited list of configuration
                  properties before parsing the URL or applying
                  user-specified properties. These configurations are
                  explained in the 'Configurations' of the
                  documentation.
                </p>



                <p>
                  Since version: 3.1.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>authenticationPlugins</strong></span>
                </p>



                <p>
                  Comma-delimited list of classes that implement
                  com.mysql.jdbc.AuthenticationPlugin and which will be
                  used for authentication unless disabled by
                  "disabledAuthenticationPlugins" property.
                </p>



                <p>
                  Since version: 5.1.19
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>defaultAuthenticationPlugin</strong></span>
                </p>



                <p>
                  Name of a class implementing
                  com.mysql.jdbc.AuthenticationPlugin which will be used
                  as the default authentication plugin (see below). It
                  is an error to use a class which is not listed in
                  "authenticationPlugins" nor it is one of the built-in
                  plugins. It is an error to set as default a plugin
                  which was disabled with
                  "disabledAuthenticationPlugins" property. It is an
                  error to set this value to null or the empty string
                  (i.e. there must be at least a valid default
                  authentication plugin specified for the connection,
                  meeting all constraints listed above).
                </p>



                <p>
                  Default:
                  com.mysql.jdbc.authentication.MysqlNativePasswordPlugin
                </p>



                <p>
                  Since version: 5.1.19
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>disabledAuthenticationPlugins</strong></span>
                </p>



                <p>
                  Comma-delimited list of classes implementing
                  com.mysql.jdbc.AuthenticationPlugin or mechanisms,
                  i.e. "mysql_native_password". The authentication
                  plugins or mechanisms listed will not be used for
                  authentication which will fail if it requires one of
                  them. It is an error to disable the default
                  authentication plugin (either the one named by
                  "defaultAuthenticationPlugin" property or the
                  hard-coded one if "defaultAuthenticationPlugin"
                  property is not set).
                </p>



                <p>
                  Since version: 5.1.19
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>disconnectOnExpiredPasswords</strong></span>
                </p>



                <p>
                  If "disconnectOnExpiredPasswords" is set to "false"
                  and password is expired then server enters "sandbox"
                  mode and sends ERR(08001, ER_MUST_CHANGE_PASSWORD) for
                  all commands that are not needed to set a new password
                  until a new password is set.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.23
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>interactiveClient</strong></span>
                </p>



                <p>
                  Set the CLIENT_INTERACTIVE flag, which tells MySQL to
                  timeout connections based on INTERACTIVE_TIMEOUT
                  instead of WAIT_TIMEOUT
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>localSocketAddress</strong></span>
                </p>



                <p>
                  Hostname or IP address given to explicitly configure
                  the interface that the driver will bind the client
                  side of the TCP/IP connection to when connecting.
                </p>



                <p>
                  Since version: 5.0.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>propertiesTransform</strong></span>
                </p>



                <p>
                  An implementation of
                  com.mysql.jdbc.ConnectionPropertiesTransform that the
                  driver will use to modify URL properties passed to the
                  driver before attempting a connection
                </p>



                <p>
                  Since version: 3.1.4
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useCompression</strong></span>
                </p>



                <p>
                  Use zlib compression when communicating with the
                  server (true/false)? Defaults to 'false'.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.0.17
                </p></td></tr></tbody></table></div><p>
    </p><p><b>Networking. </b>
      </p><div class="informaltable"><table summary="This table lists Connector/J Networking connection
          properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
                  <span class="strong"><strong>socksProxyHost</strong></span>
                </p>



                <p>
                  Name or IP address of SOCKS host to connect through.
                </p>



                <p>
                  Since version: 5.1.34
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>socksProxyPort</strong></span>
                </p>



                <p>
                  Port of SOCKS server.
                </p>



                <p>
                  Default: 1080
                </p>



                <p>
                  Since version: 5.1.34
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>maxAllowedPacket</strong></span>
                </p>



                <p>
                  Maximum allowed packet size to send to server. If not
                  set, the value of system variable 'max_allowed_packet'
                  will be used to initialize this upon connecting. This
                  value will not take effect if set larger than the
                  value of 'max_allowed_packet'. Also, due to an
                  internal dependency with the property
                  "blobSendChunkSize", this setting has a minimum value
                  of "8203" if "useServerPrepStmts" is set to "true".
                </p>



                <p>
                  Default: -1
                </p>



                <p>
                  Since version: 5.1.8
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>tcpKeepAlive</strong></span>
                </p>



                <p>
                  If connecting using TCP/IP, should the driver set
                  SO_KEEPALIVE?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.0.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>tcpNoDelay</strong></span>
                </p>



                <p>
                  If connecting using TCP/IP, should the driver set
                  SO_TCP_NODELAY (disabling the Nagle Algorithm)?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.0.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>tcpRcvBuf</strong></span>
                </p>



                <p>
                  If connecting using TCP/IP, should the driver set
                  SO_RCV_BUF to the given value? The default value of
                  '0', means use the platform default value for this
                  property)
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 5.0.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>tcpSndBuf</strong></span>
                </p>



                <p>
                  If connecting using TCP/IP, should the driver set
                  SO_SND_BUF to the given value? The default value of
                  '0', means use the platform default value for this
                  property)
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 5.0.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>tcpTrafficClass</strong></span>
                </p>



                <p>
                  If connecting using TCP/IP, should the driver set
                  traffic class or type-of-service fields ?See the
                  documentation for java.net.Socket.setTrafficClass()
                  for more information.
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 5.0.7
                </p></td></tr></tbody></table></div><p>
    </p><p><b>High Availability and Clustering. </b>
      </p><div class="informaltable"><table summary="This table lists Connector/J High Availability and
          Clustering connection properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
                  <span class="strong"><strong>autoReconnect</strong></span>
                </p>



                <p>
                  Should the driver try to re-establish stale and/or
                  dead connections? If enabled the driver will throw an
                  exception for a queries issued on a stale or dead
                  connection, which belong to the current transaction,
                  but will attempt reconnect before the next query
                  issued on the connection in a new transaction. The use
                  of this feature is not recommended, because it has
                  side effects related to session state and data
                  consistency when applications don't handle
                  SQLExceptions properly, and is only designed to be
                  used when you are unable to configure your application
                  to handle SQLExceptions resulting from dead and stale
                  connections properly. Alternatively, as a last option,
                  investigate setting the MySQL server variable
                  "wait_timeout" to a high value, rather than the
                  default of 8 hours.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>autoReconnectForPools</strong></span>
                </p>



                <p>
                  Use a reconnection strategy appropriate for connection
                  pools (defaults to 'false')
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>failOverReadOnly</strong></span>
                </p>



                <p>
                  When failing over in autoReconnect mode, should the
                  connection be set to 'read-only'?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.0.12
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>maxReconnects</strong></span>
                </p>



                <p>
                  Maximum number of reconnects to attempt if
                  autoReconnect is true, default is '3'.
                </p>



                <p>
                  Default: 3
                </p>



                <p>
                  Since version: 1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>reconnectAtTxEnd</strong></span>
                </p>



                <p>
                  If autoReconnect is set to true, should the driver
                  attempt reconnections at the end of every transaction?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.0.10
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>retriesAllDown</strong></span>
                </p>



                <p>
                  When using loadbalancing or failover, the number of
                  times the driver should cycle through available hosts,
                  attempting to connect. Between cycles, the driver will
                  pause for 250ms if no servers are available.
                </p>



                <p>
                  Default: 120
                </p>



                <p>
                  Since version: 5.1.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>initialTimeout</strong></span>
                </p>



                <p>
                  If autoReconnect is enabled, the initial time to wait
                  between re-connect attempts (in seconds, defaults to
                  '2').
                </p>



                <p>
                  Default: 2
                </p>



                <p>
                  Since version: 1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>roundRobinLoadBalance</strong></span>
                </p>



                <p>
                  When autoReconnect is enabled, and failoverReadonly is
                  false, should we pick hosts to connect to on a
                  round-robin basis?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>queriesBeforeRetryMaster</strong></span>
                </p>



                <p>
                  Number of queries to issue before falling back to the
                  primary host when failed over (when using multi-host
                  failover). Whichever condition is met first,
                  'queriesBeforeRetryMaster' or
                  'secondsBeforeRetryMaster' will cause an attempt to be
                  made to reconnect to the primary host. Setting both
                  properties to 0 disables the automatic fall back to
                  the primary host at transaction boundaries. Defaults
                  to 50.
                </p>



                <p>
                  Default: 50
                </p>



                <p>
                  Since version: 3.0.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>secondsBeforeRetryMaster</strong></span>
                </p>



                <p>
                  How long should the driver wait, when failed over,
                  before attempting to reconnect to the primary host?
                  Whichever condition is met first,
                  'queriesBeforeRetryMaster' or
                  'secondsBeforeRetryMaster' will cause an attempt to be
                  made to reconnect to the master. Setting both
                  properties to 0 disables the automatic fall back to
                  the primary host at transaction boundaries. Time in
                  seconds, defaults to 30
                </p>



                <p>
                  Default: 30
                </p>



                <p>
                  Since version: 3.0.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>allowMasterDownConnections</strong></span>
                </p>



                <p>
                  Should replication-aware driver establish connections
                  to slaves when connection to master servers cannot be
                  established at initial connection? Defaults to
                  'false', which will cause SQLException when configured
                  master hosts are all unavailable when establishing a
                  new replication-aware Connection.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.27
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>replicationEnableJMX</strong></span>
                </p>



                <p>
                  Enables JMX-based management of load-balanced
                  connection groups, including live addition/removal of
                  hosts from load-balancing pool.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.27
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>selfDestructOnPingMaxOperations</strong></span>
                </p>



                <p>
                  =If set to a non-zero value, the driver will report
                  close the connection and report failure when
                  Connection.ping() or Connection.isValid(int) is called
                  if the connection's count of commands sent to the
                  server exceeds this value.
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 5.1.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>selfDestructOnPingSecondsLifetime</strong></span>
                </p>



                <p>
                  If set to a non-zero value, the driver will report
                  close the connection and report failure when
                  Connection.ping() or Connection.isValid(int) is called
                  if the connection's lifetime exceeds this value.
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 5.1.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>resourceId</strong></span>
                </p>



                <p>
                  A globally unique name that identifies the resource
                  that this datasource or connection is connected to,
                  used for XAResource.isSameRM() when the driver can't
                  determine this value based on hostnames used in the
                  URL
                </p>



                <p>
                  Since version: 5.0.1
                </p></td></tr></tbody></table></div><p>
    </p><p><b>Security. </b>
      </p><div class="informaltable"><table summary="This table lists Connector/J Security connection
          properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
                  <span class="strong"><strong>allowMultiQueries</strong></span>
                </p>



                <p>
                  Allow the use of ';' to delimit multiple queries
                  during one statement (true/false), defaults to
                  'false', and does not affect the addBatch() and
                  executeBatch() methods, which instead rely on
                  rewriteBatchStatements.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useSSL</strong></span>
                </p>



                <p>
                  Use SSL when communicating with the server
                  (true/false), defaults to 'false'
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.0.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>requireSSL</strong></span>
                </p>



                <p>
                  Require server support of SSL connection if
                  useSSL=true? (defaults to 'false').
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>verifyServerCertificate</strong></span>
                </p>



                <p>
                  If "useSSL" is set to "true", should the driver verify
                  the server's certificate? When using this feature, the
                  keystore parameters should be specified by the
                  "clientCertificateKeyStore*" properties, rather than
                  system properties.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>clientCertificateKeyStoreUrl</strong></span>
                </p>



                <p>
                  URL to the client certificate KeyStore (if not
                  specified, use defaults)
                </p>



                <p>
                  Since version: 5.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>clientCertificateKeyStoreType</strong></span>
                </p>



                <p>
                  KeyStore type for client certificates (NULL or empty
                  means use the default, which is "JKS". Standard
                  keystore types supported by the JVM are "JKS" and
                  "PKCS12", your environment may have more available
                  depending on what security products are installed and
                  available to the JVM.
                </p>



                <p>
                  Default: JKS
                </p>



                <p>
                  Since version: 5.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>clientCertificateKeyStorePassword</strong></span>
                </p>



                <p>
                  Password for the client certificates KeyStore
                </p>



                <p>
                  Since version: 5.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>trustCertificateKeyStoreUrl</strong></span>
                </p>



                <p>
                  URL to the trusted root certificate KeyStore (if not
                  specified, use defaults)
                </p>



                <p>
                  Since version: 5.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>trustCertificateKeyStoreType</strong></span>
                </p>



                <p>
                  KeyStore type for trusted root certificates (NULL or
                  empty means use the default, which is "JKS". Standard
                  keystore types supported by the JVM are "JKS" and
                  "PKCS12", your environment may have more available
                  depending on what security products are installed and
                  available to the JVM.
                </p>



                <p>
                  Default: JKS
                </p>



                <p>
                  Since version: 5.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>trustCertificateKeyStorePassword</strong></span>
                </p>



                <p>
                  Password for the trusted root certificates KeyStore
                </p>



                <p>
                  Since version: 5.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>enabledSSLCipherSuites</strong></span>
                </p>



                <p>
                  If "useSSL" is set to "true", sets the cipher suites
                  enabled for use on the underlying SSL sockets. This
                  may be required when using external JSSE providers or
                  to specify compatible cipher suites when connecting to
                  newer, more secure, MySQL server versions and running
                  the driver with older JVMs.
                </p>



                <p>
                  Since version: 5.1.35
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>allowLoadLocalInfile</strong></span>
                </p>



                <p>
                  Should the driver allow use of 'LOAD DATA LOCAL
                  INFILE...' (defaults to 'true').
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.0.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>allowUrlInLocalInfile</strong></span>
                </p>



                <p>
                  Should the driver allow URLs in 'LOAD DATA LOCAL
                  INFILE' statements?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.4
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>allowPublicKeyRetrieval</strong></span>
                </p>



                <p>
                  Allows special handshake roundtrip to get server RSA
                  public key directly from server.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.31
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>paranoid</strong></span>
                </p>



                <p>
                  Take measures to prevent exposure sensitive
                  information in error messages and clear data
                  structures holding sensitive data when possible?
                  (defaults to 'false')
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.0.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>passwordCharacterEncoding</strong></span>
                </p>



                <p>
                  What character encoding is used for passwords? Leaving
                  this set to the default value (null), uses the value
                  set in "characterEncoding" if there is one, otherwise
                  uses UTF-8 as default encoding. If the password
                  contains non-ASCII characters, the password encoding
                  must match what server encoding was set to when the
                  password was created. For passwords in other character
                  encodings, the encoding will have to be specified with
                  this property (or with "characterEncoding"), as it's
                  not possible for the driver to auto-detect this.
                </p>



                <p>
                  Since version: 5.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>serverRSAPublicKeyFile</strong></span>
                </p>



                <p>
                  File path to the server RSA public key file for
                  sha256_password authentication. If not specified, the
                  public key will be retrieved from the server.
                </p>



                <p>
                  Since version: 5.1.31
                </p></td></tr></tbody></table></div><p>
    </p><p><b>Performance Extensions. </b>
      </p><div class="informaltable"><table summary="This table lists Connector/J Performance Extensions
          connection properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
                  <span class="strong"><strong>callableStmtCacheSize</strong></span>
                </p>



                <p>
                  If 'cacheCallableStmts' is enabled, how many callable
                  statements should be cached?
                </p>



                <p>
                  Default: 100
                </p>



                <p>
                  Since version: 3.1.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>metadataCacheSize</strong></span>
                </p>



                <p>
                  The number of queries to cache ResultSetMetadata for
                  if cacheResultSetMetaData is set to 'true' (default
                  50)
                </p>



                <p>
                  Default: 50
                </p>



                <p>
                  Since version: 3.1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useLocalSessionState</strong></span>
                </p>



                <p>
                  Should the driver refer to the internal values of
                  autocommit and transaction isolation that are set by
                  Connection.setAutoCommit() and
                  Connection.setTransactionIsolation() and transaction
                  state as maintained by the protocol, rather than
                  querying the database or blindly sending commands to
                  the database for commit() or rollback() method calls?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useLocalTransactionState</strong></span>
                </p>



                <p>
                  Should the driver use the in-transaction state
                  provided by the MySQL protocol to determine if a
                  commit() or rollback() should actually be sent to the
                  database?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>prepStmtCacheSize</strong></span>
                </p>



                <p>
                  If prepared statement caching is enabled, how many
                  prepared statements should be cached?
                </p>



                <p>
                  Default: 25
                </p>



                <p>
                  Since version: 3.0.10
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>prepStmtCacheSqlLimit</strong></span>
                </p>



                <p>
                  If prepared statement caching is enabled, what's the
                  largest SQL the driver will cache the parsing for?
                </p>



                <p>
                  Default: 256
                </p>



                <p>
                  Since version: 3.0.10
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>parseInfoCacheFactory</strong></span>
                </p>



                <p>
                  Name of a class implementing
                  com.mysql.jdbc.CacheAdapterFactory, which will be used
                  to create caches for the parsed representation of
                  client-side prepared statements.
                </p>



                <p>
                  Default: com.mysql.jdbc.PerConnectionLRUFactory
                </p>



                <p>
                  Since version: 5.1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>serverConfigCacheFactory</strong></span>
                </p>



                <p>
                  Name of a class implementing
                  com.mysql.jdbc.CacheAdapterFactory&lt;String,
                  Map&lt;String, String&gt;&gt;, which will be used to
                  create caches for MySQL server configuration values
                </p>



                <p>
                  Default: com.mysql.jdbc.PerVmServerConfigCacheFactory
                </p>



                <p>
                  Since version: 5.1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>alwaysSendSetIsolation</strong></span>
                </p>



                <p>
                  Should the driver always communicate with the database
                  when Connection.setTransactionIsolation() is called?
                  If set to false, the driver will only communicate with
                  the database when the requested transaction isolation
                  is different than the whichever is newer, the last
                  value that was set via
                  Connection.setTransactionIsolation(), or the value
                  that was read from the server when the connection was
                  established. Note that useLocalSessionState=true will
                  force the same behavior as
                  alwaysSendSetIsolation=false, regardless of how
                  alwaysSendSetIsolation is set.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>maintainTimeStats</strong></span>
                </p>



                <p>
                  Should the driver maintain various internal timers to
                  enable idle time calculations as well as more verbose
                  error messages when the connection to the server
                  fails? Setting this property to false removes at least
                  two calls to System.getCurrentTimeMillis() per query.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.9
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useCursorFetch</strong></span>
                </p>



                <p>
                  If connected to MySQL &gt; 5.0.2, and setFetchSize()
                  &gt; 0 on a statement, should that statement use
                  cursor-based fetching to retrieve rows?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>blobSendChunkSize</strong></span>
                </p>



                <p>
                  Chunk size to use when sending BLOB/CLOBs via
                  ServerPreparedStatements. Note that this value cannot
                  exceed the value of "maxAllowedPacket" and, if that is
                  the case, then this value will be corrected
                  automatically.
                </p>



                <p>
                  Default: 1048576
                </p>



                <p>
                  Since version: 3.1.9
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>cacheCallableStmts</strong></span>
                </p>



                <p>
                  Should the driver cache the parsing stage of
                  CallableStatements
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>cachePrepStmts</strong></span>
                </p>



                <p>
                  Should the driver cache the parsing stage of
                  PreparedStatements of client-side prepared statements,
                  the "check" for suitability of server-side prepared
                  and server-side prepared statements themselves?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.0.10
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>cacheResultSetMetadata</strong></span>
                </p>



                <p>
                  Should the driver cache ResultSetMetaData for
                  Statements and PreparedStatements? (Req. JDK-1.4+,
                  true/false, default 'false')
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>cacheServerConfiguration</strong></span>
                </p>



                <p>
                  Should the driver cache the results of 'SHOW
                  VARIABLES' and 'SHOW COLLATION' on a per-URL basis?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>defaultFetchSize</strong></span>
                </p>



                <p>
                  The driver will call setFetchSize(n) with this value
                  on all newly-created Statements
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 3.1.9
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>dontCheckOnDuplicateKeyUpdateInSQL</strong></span>
                </p>



                <p>
                  Stops checking if every INSERT statement contains the
                  "ON DUPLICATE KEY UPDATE" clause. As a side effect,
                  obtaining the statement's generated keys information
                  will return a list where normally it wouldn't. Also be
                  aware that, in this case, the list of generated keys
                  returned may not be accurate. The effect of this
                  property is canceled if set simultaneously with
                  'rewriteBatchedStatements=true'.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.32
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>dontTrackOpenResources</strong></span>
                </p>



                <p>
                  The JDBC specification requires the driver to
                  automatically track and close resources, however if
                  your application doesn't do a good job of explicitly
                  calling close() on statements or result sets, this can
                  cause memory leakage. Setting this property to true
                  relaxes this constraint, and can be more memory
                  efficient for some applications. Also the automatic
                  closing of the Statement and current ResultSet in
                  Statement.closeOnCompletion() and
                  Statement.getMoreResults
                  ([Statement.CLOSE_CURRENT_RESULT |
                  Statement.CLOSE_ALL_RESULTS]), respectively, ceases to
                  happen. This property automatically sets
                  holdResultsOpenOverStatementClose=true.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>dynamicCalendars</strong></span>
                </p>



                <p>
                  Should the driver retrieve the default calendar when
                  required, or cache it per connection/session?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>elideSetAutoCommits</strong></span>
                </p>



                <p>
                  If using MySQL-4.1 or newer, should the driver only
                  issue 'set autocommit=n' queries when the server's
                  state doesn't match the requested state by
                  Connection.setAutoCommit(boolean)?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>enableEscapeProcessing</strong></span>
                </p>



                <p>
                  Sets the default escape processing behavior for
                  Statement objects. The method
                  Statement.setEscapeProcessing() can be used to specify
                  the escape processing behavior for an individual
                  Statement object. Default escape processing behavior
                  in prepared statements must be defined with the
                  property 'processEscapeCodesForPrepStmts'.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.37
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>enableQueryTimeouts</strong></span>
                </p>



                <p>
                  When enabled, query timeouts set via
                  Statement.setQueryTimeout() use a shared
                  java.util.Timer instance for scheduling. Even if the
                  timeout doesn't expire before the query is processed,
                  there will be memory used by the TimerTask for the
                  given timeout which won't be reclaimed until the time
                  the timeout would have expired if it hadn't been
                  cancelled by the driver. High-load environments might
                  want to consider disabling this functionality.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.0.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>holdResultsOpenOverStatementClose</strong></span>
                </p>



                <p>
                  Should the driver close result sets on
                  Statement.close() as required by the JDBC
                  specification?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>largeRowSizeThreshold</strong></span>
                </p>



                <p>
                  What size result set row should the JDBC driver
                  consider "large", and thus use a more memory-efficient
                  way of representing the row internally?
                </p>



                <p>
                  Default: 2048
                </p>



                <p>
                  Since version: 5.1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalanceStrategy</strong></span>
                </p>



                <p>
                  If using a load-balanced connection to connect to SQL
                  nodes in a MySQL Cluster/NDB configuration (by using
                  the URL prefix "jdbc:mysql:loadbalance://"), which
                  load balancing algorithm should the driver use: (1)
                  "random" - the driver will pick a random host for each
                  request. This tends to work better than round-robin,
                  as the randomness will somewhat account for spreading
                  loads where requests vary in response time, while
                  round-robin can sometimes lead to overloaded nodes if
                  there are variations in response times across the
                  workload. (2) "bestResponseTime" - the driver will
                  route the request to the host that had the best
                  response time for the previous transaction.
                </p>



                <p>
                  Default: random
                </p>



                <p>
                  Since version: 5.0.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>locatorFetchBufferSize</strong></span>
                </p>



                <p>
                  If 'emulateLocators' is configured to 'true', what
                  size buffer should be used when fetching BLOB data for
                  getBinaryInputStream?
                </p>



                <p>
                  Default: 1048576
                </p>



                <p>
                  Since version: 3.2.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>readOnlyPropagatesToServer</strong></span>
                </p>



                <p>
                  Should the driver issue appropriate statements to
                  implicitly set the transaction access mode on server
                  side when Connection.setReadOnly() is called? Setting
                  this property to 'true' enables InnoDB read-only
                  potential optimizations but also requires an extra
                  roundtrip to set the right transaction state. Even if
                  this property is set to 'false', the driver will do
                  its best effort to prevent the execution of
                  database-state-changing queries. Requires minimum of
                  MySQL 5.6.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.35
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>rewriteBatchedStatements</strong></span>
                </p>



                <p>
                  Should the driver use multiqueries (irregardless of
                  the setting of "allowMultiQueries") as well as
                  rewriting of prepared statements for INSERT into
                  multi-value inserts when executeBatch() is called?
                  Notice that this has the potential for SQL injection
                  if using plain java.sql.Statements and your code
                  doesn't sanitize input correctly. Notice that for
                  prepared statements, server-side prepared statements
                  can not currently take advantage of this rewrite
                  option, and that if you don't specify stream lengths
                  when using PreparedStatement.set*Stream(), the driver
                  won't be able to determine the optimum number of
                  parameters per batch and you might receive an error
                  from the driver that the resultant packet is too
                  large. Statement.getGeneratedKeys() for these
                  rewritten statements only works when the entire batch
                  includes INSERT statements. Please be aware using
                  rewriteBatchedStatements=true with INSERT .. ON
                  DUPLICATE KEY UPDATE that for rewritten statement
                  server returns only one value as sum of all affected
                  (or found) rows in batch and it isn't possible to map
                  it correctly to initial statements; in this case
                  driver returns 0 as a result of each batch statement
                  if total count was 0, and the
                  Statement.SUCCESS_NO_INFO as a result of each batch
                  statement if total count was &gt; 0.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useDirectRowUnpack</strong></span>
                </p>



                <p>
                  Use newer result set row unpacking code that skips a
                  copy from network buffers to a MySQL packet instance
                  and instead reads directly into the result set row
                  data buffers.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useDynamicCharsetInfo</strong></span>
                </p>



                <p>
                  Should the driver use a per-connection cache of
                  character set information queried from the server when
                  necessary, or use a built-in static mapping that is
                  more efficient, but isn't aware of custom character
                  sets or character sets implemented after the release
                  of the JDBC driver?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.0.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useFastDateParsing</strong></span>
                </p>



                <p>
                  Use internal String-&gt;Date/Time/Timestamp conversion
                  routines to avoid excessive object creation? This is
                  part of the legacy date-time code, thus the property
                  has an effect only when "useLegacyDatetimeCode=true."
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.0.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useFastIntParsing</strong></span>
                </p>



                <p>
                  Use internal String-&gt;Integer conversion routines to
                  avoid excessive object creation?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.4
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useJvmCharsetConverters</strong></span>
                </p>



                <p>
                  Always use the character encoding routines built into
                  the JVM, rather than using lookup tables for
                  single-byte character sets?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useReadAheadInput</strong></span>
                </p>



                <p>
                  Use newer, optimized non-blocking, buffered input
                  stream when reading from the server?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.5
                </p></td></tr></tbody></table></div><p>
    </p><p><b>Debugging/Profiling. </b>
      </p><div class="informaltable"><table summary="This table lists Connector/J Debugging/Profiling
          connection properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
                  <span class="strong"><strong>logger</strong></span>
                </p>



                <p>
                  The name of a class that implements
                  "com.mysql.jdbc.log.Log" that will be used to log
                  messages to. (default is
                  "com.mysql.jdbc.log.StandardLogger", which logs to
                  STDERR)
                </p>



                <p>
                  Default: com.mysql.jdbc.log.StandardLogger
                </p>



                <p>
                  Since version: 3.1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>gatherPerfMetrics</strong></span>
                </p>



                <p>
                  Should the driver gather performance metrics, and
                  report them via the configured logger every
                  'reportMetricsIntervalMillis' milliseconds?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>profileSQL</strong></span>
                </p>



                <p>
                  Trace queries and their execution/fetch times to the
                  configured logger (true/false) defaults to 'false'
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>profileSql</strong></span>
                </p>



                <p>
                  Deprecated, use 'profileSQL' instead. Trace queries
                  and their execution/fetch times on STDERR (true/false)
                  defaults to 'false'
                </p>



                <p>
                  Since version: 2.0.14
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>reportMetricsIntervalMillis</strong></span>
                </p>



                <p>
                  If 'gatherPerfMetrics' is enabled, how often should
                  they be logged (in ms)?
                </p>



                <p>
                  Default: 30000
                </p>



                <p>
                  Since version: 3.1.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>maxQuerySizeToLog</strong></span>
                </p>



                <p>
                  Controls the maximum length/size of a query that will
                  get logged when profiling or tracing
                </p>



                <p>
                  Default: 2048
                </p>



                <p>
                  Since version: 3.1.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>packetDebugBufferSize</strong></span>
                </p>



                <p>
                  The maximum number of packets to retain when
                  'enablePacketDebug' is true
                </p>



                <p>
                  Default: 20
                </p>



                <p>
                  Since version: 3.1.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>slowQueryThresholdMillis</strong></span>
                </p>



                <p>
                  If 'logSlowQueries' is enabled, how long should a
                  query (in ms) before it is logged as 'slow'?
                </p>



                <p>
                  Default: 2000
                </p>



                <p>
                  Since version: 3.1.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>slowQueryThresholdNanos</strong></span>
                </p>



                <p>
                  If 'useNanosForElapsedTime' is set to true, and this
                  property is set to a non-zero value, the driver will
                  use this threshold (in nanosecond units) to determine
                  if a query was slow.
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 5.0.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useUsageAdvisor</strong></span>
                </p>



                <p>
                  Should the driver issue 'usage' warnings advising
                  proper and efficient usage of JDBC and MySQL
                  Connector/J to the log (true/false, defaults to
                  'false')?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>autoGenerateTestcaseScript</strong></span>
                </p>



                <p>
                  Should the driver dump the SQL it is executing,
                  including server-side prepared statements to STDERR?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.9
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>autoSlowLog</strong></span>
                </p>



                <p>
                  Instead of using slowQueryThreshold* to determine if a
                  query is slow enough to be logged, maintain statistics
                  that allow the driver to determine queries that are
                  outside the 99th percentile?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.4
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>clientInfoProvider</strong></span>
                </p>



                <p>
                  The name of a class that implements the
                  com.mysql.jdbc.JDBC4ClientInfoProvider interface in
                  order to support JDBC-4.0's
                  Connection.get/setClientInfo() methods
                </p>



                <p>
                  Default: com.mysql.jdbc.JDBC4CommentClientInfoProvider
                </p>



                <p>
                  Since version: 5.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>dumpMetadataOnColumnNotFound</strong></span>
                </p>



                <p>
                  Should the driver dump the field-level metadata of a
                  result set into the exception message when
                  ResultSet.findColumn() fails?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>dumpQueriesOnException</strong></span>
                </p>



                <p>
                  Should the driver dump the contents of the query sent
                  to the server in the message for SQLExceptions?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>enablePacketDebug</strong></span>
                </p>



                <p>
                  When enabled, a ring-buffer of 'packetDebugBufferSize'
                  packets will be kept, and dumped when exceptions are
                  thrown in key areas in the driver's code
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>explainSlowQueries</strong></span>
                </p>



                <p>
                  If 'logSlowQueries' is enabled, should the driver
                  automatically issue an 'EXPLAIN' on the server and
                  send the results to the configured log at a WARN
                  level?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>includeInnodbStatusInDeadlockExceptions</strong></span>
                </p>



                <p>
                  Include the output of "SHOW ENGINE INNODB STATUS" in
                  exception messages when deadlock exceptions are
                  detected?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>includeThreadDumpInDeadlockExceptions</strong></span>
                </p>



                <p>
                  Include a current Java thread dump in exception
                  messages when deadlock exceptions are detected?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.15
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>includeThreadNamesAsStatementComment</strong></span>
                </p>



                <p>
                  Include the name of the current thread as a comment
                  visible in "SHOW PROCESSLIST", or in Innodb deadlock
                  dumps, useful in correlation with
                  "includeInnodbStatusInDeadlockExceptions=true" and
                  "includeThreadDumpInDeadlockExceptions=true".
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.15
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>logSlowQueries</strong></span>
                </p>



                <p>
                  Should queries that take longer than
                  'slowQueryThresholdMillis' be logged?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>logXaCommands</strong></span>
                </p>



                <p>
                  Should the driver log XA commands sent by
                  MysqlXaConnection to the server, at the DEBUG level of
                  logging?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>profilerEventHandler</strong></span>
                </p>



                <p>
                  Name of a class that implements the interface
                  com.mysql.jdbc.profiler.ProfilerEventHandler that will
                  be used to handle profiling/tracing events.
                </p>



                <p>
                  Default:
                  com.mysql.jdbc.profiler.LoggingProfilerEventHandler
                </p>



                <p>
                  Since version: 5.1.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>resultSetSizeThreshold</strong></span>
                </p>



                <p>
                  If the usage advisor is enabled, how many rows should
                  a result set contain before the driver warns that it
                  is suspiciously large?
                </p>



                <p>
                  Default: 100
                </p>



                <p>
                  Since version: 5.0.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>traceProtocol</strong></span>
                </p>



                <p>
                  Should trace-level network protocol be logged?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useNanosForElapsedTime</strong></span>
                </p>



                <p>
                  For profiling/debugging functionality that measures
                  elapsed time, should the driver try to use nanoseconds
                  resolution if available (JDK &gt;= 1.5)?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.7
                </p></td></tr></tbody></table></div><p>
    </p><p><b>Miscellaneous. </b>
      </p><div class="informaltable"><table summary="This table lists Connector/J Miscellaneous connection
          properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
                  <span class="strong"><strong>useUnicode</strong></span>
                </p>



                <p>
                  Should the driver use Unicode character encodings when
                  handling strings? Should only be used when the driver
                  can't determine the character set mapping, or you are
                  trying to 'force' the driver to use a character set
                  that MySQL either doesn't natively support (such as
                  UTF-8), true/false, defaults to 'true'
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 1.1g
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>characterEncoding</strong></span>
                </p>



                <p>
                  If 'useUnicode' is set to true, what character
                  encoding should the driver use when dealing with
                  strings? (defaults is to 'autodetect')
                </p>



                <p>
                  Since version: 1.1g
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>characterSetResults</strong></span>
                </p>



                <p>
                  Character set to tell the server to return results as.
                </p>



                <p>
                  Since version: 3.0.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>connectionAttributes</strong></span>
                </p>



                <p>
                  A comma-delimited list of user-defined key:value pairs
                  (in addition to standard MySQL-defined key:value
                  pairs) to be passed to MySQL Server for display as
                  connection attributes in the
                  PERFORMANCE_SCHEMA.SESSION_CONNECT_ATTRS table.
                  Example usage:
                  connectionAttributes=key1:value1,key2:value2 This
                  functionality is available for use with MySQL Server
                  version 5.6 or later only. Earlier versions of MySQL
                  Server do not support connection attributes, causing
                  this configuration option to be ignored. Setting
                  connectionAttributes=none will cause connection
                  attribute processing to be bypassed, for situations
                  where Connection creation/initialization speed is
                  critical.
                </p>



                <p>
                  Since version: 5.1.25
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>connectionCollation</strong></span>
                </p>



                <p>
                  If set, tells the server to use this collation via
                  'set collation_connection'
                </p>



                <p>
                  Since version: 3.0.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useBlobToStoreUTF8OutsideBMP</strong></span>
                </p>



                <p>
                  Tells the driver to treat [MEDIUM/LONG]BLOB columns as
                  [LONG]VARCHAR columns holding text encoded in UTF-8
                  that has characters outside the BMP (4-byte
                  encodings), which MySQL server can't handle natively.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>utf8OutsideBmpExcludedColumnNamePattern</strong></span>
                </p>



                <p>
                  When "useBlobToStoreUTF8OutsideBMP" is set to "true",
                  column names matching the given regex will still be
                  treated as BLOBs unless they match the regex specified
                  for "utf8OutsideBmpIncludedColumnNamePattern". The
                  regex must follow the patterns used for the
                  java.util.regex package.
                </p>



                <p>
                  Since version: 5.1.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>utf8OutsideBmpIncludedColumnNamePattern</strong></span>
                </p>



                <p>
                  Used to specify exclusion rules to
                  "utf8OutsideBmpExcludedColumnNamePattern". The regex
                  must follow the patterns used for the java.util.regex
                  package.
                </p>



                <p>
                  Since version: 5.1.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalanceEnableJMX</strong></span>
                </p>



                <p>
                  Enables JMX-based management of load-balanced
                  connection groups, including live addition/removal of
                  hosts from load-balancing pool.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>sessionVariables</strong></span>
                </p>



                <p>
                  A comma-separated list of name/value pairs to be sent
                  as SET SESSION ... to the server when the driver
                  connects.
                </p>



                <p>
                  Since version: 3.1.8
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useColumnNamesInFindColumn</strong></span>
                </p>



                <p>
                  Prior to JDBC-4.0, the JDBC specification had a bug
                  related to what could be given as a "column name" to
                  ResultSet methods like findColumn(), or getters that
                  took a String property. JDBC-4.0 clarified "column
                  name" to mean the label, as given in an "AS" clause
                  and returned by ResultSetMetaData.getColumnLabel(),
                  and if no AS clause, the column name. Setting this
                  property to "true" will give behavior that is
                  congruent to JDBC-3.0 and earlier versions of the JDBC
                  specification, but which because of the specification
                  bug could give unexpected results. This property is
                  preferred over "useOldAliasMetadataBehavior" unless
                  you need the specific behavior that it provides with
                  respect to ResultSetMetadata.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>allowNanAndInf</strong></span>
                </p>



                <p>
                  Should the driver allow NaN or +/- INF values in
                  PreparedStatement.setDouble()?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>autoClosePStmtStreams</strong></span>
                </p>



                <p>
                  Should the driver automatically call .close() on
                  streams/readers passed as arguments via set*()
                  methods?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.12
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>autoDeserialize</strong></span>
                </p>



                <p>
                  Should the driver automatically detect and
                  de-serialize objects stored in BLOB fields?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>blobsAreStrings</strong></span>
                </p>



                <p>
                  Should the driver always treat BLOBs as Strings -
                  specifically to work around dubious metadata returned
                  by the server for GROUP BY clauses?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.8
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>cacheDefaultTimezone</strong></span>
                </p>



                <p>
                  Caches client's default time zone. This results in
                  better performance when dealing with time zone
                  conversions in Date and Time data types, however it
                  won't be aware of time zone changes if they happen at
                  runtime.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.35
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>capitalizeTypeNames</strong></span>
                </p>



                <p>
                  Capitalize type names in DatabaseMetaData? (usually
                  only useful when using WebObjects, true/false,
                  defaults to 'false')
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 2.0.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>clobCharacterEncoding</strong></span>
                </p>



                <p>
                  The character encoding to use for sending and
                  retrieving TEXT, MEDIUMTEXT and LONGTEXT values
                  instead of the configured connection characterEncoding
                </p>



                <p>
                  Since version: 5.0.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>clobberStreamingResults</strong></span>
                </p>



                <p>
                  This will cause a 'streaming' ResultSet to be
                  automatically closed, and any outstanding data still
                  streaming from the server to be discarded if another
                  query is executed before all the data has been read
                  from the server.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.0.9
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>compensateOnDuplicateKeyUpdateCounts</strong></span>
                </p>



                <p>
                  Should the driver compensate for the update counts of
                  "ON DUPLICATE KEY" INSERT statements (2 = 1, 0 = 1)
                  when using prepared statements?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>continueBatchOnError</strong></span>
                </p>



                <p>
                  Should the driver continue processing batch commands
                  if one statement fails. The JDBC spec allows either
                  way (defaults to 'true').
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.0.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>createDatabaseIfNotExist</strong></span>
                </p>



                <p>
                  Creates the database given in the URL if it doesn't
                  yet exist. Assumes the configured user has permissions
                  to create databases.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.9
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>detectCustomCollations</strong></span>
                </p>



                <p>
                  Should the driver detect custom charsets/collations
                  installed on server (true/false, defaults to 'false').
                  If this option set to 'true' driver gets actual
                  charsets/collations from server each time connection
                  establishes. This could slow down connection
                  initialization significantly.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.29
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>emptyStringsConvertToZero</strong></span>
                </p>



                <p>
                  Should the driver allow conversions from empty string
                  fields to numeric values of '0'?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.8
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>emulateLocators</strong></span>
                </p>



                <p>
                  Should the driver emulate java.sql.Blobs with
                  locators? With this feature enabled, the driver will
                  delay loading the actual Blob data until the one of
                  the retrieval methods (getInputStream(), getBytes(),
                  and so forth) on the blob data stream has been
                  accessed. For this to work, you must use a column
                  alias with the value of the column to the actual name
                  of the Blob. The feature also has the following
                  restrictions: The SELECT that created the result set
                  must reference only one table, the table must have a
                  primary key; the SELECT must alias the original blob
                  column name, specified as a string, to an alternate
                  name; the SELECT must cover all columns that make up
                  the primary key.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>emulateUnsupportedPstmts</strong></span>
                </p>



                <p>
                  Should the driver detect prepared statements that are
                  not supported by the server, and replace them with
                  client-side emulated versions?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>exceptionInterceptors</strong></span>
                </p>



                <p>
                  Comma-delimited list of classes that implement
                  com.mysql.jdbc.ExceptionInterceptor. These classes
                  will be instantiated one per Connection instance, and
                  all SQLExceptions thrown by the driver will be allowed
                  to be intercepted by these interceptors, in a chained
                  fashion, with the first class listed as the head of
                  the chain.
                </p>



                <p>
                  Since version: 5.1.8
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>functionsNeverReturnBlobs</strong></span>
                </p>



                <p>
                  Should the driver always treat data from functions
                  returning BLOBs as Strings - specifically to work
                  around dubious metadata returned by the server for
                  GROUP BY clauses?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.8
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>generateSimpleParameterMetadata</strong></span>
                </p>



                <p>
                  Should the driver generate simplified parameter
                  metadata for PreparedStatements when no metadata is
                  available either because the server couldn't support
                  preparing the statement, or server-side prepared
                  statements are disabled?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>getProceduresReturnsFunctions</strong></span>
                </p>



                <p>
                  Pre-JDBC4 DatabaseMetaData API has only the
                  getProcedures() and getProcedureColumns() methods, so
                  they return metadata info for both stored procedures
                  and functions. JDBC4 was extended with the
                  getFunctions() and getFunctionColumns() methods and
                  the expected behaviours of previous methods are not
                  well defined. For JDBC4 and higher, default 'true'
                  value of the option means that calls of
                  DatabaseMetaData.getProcedures() and
                  DatabaseMetaData.getProcedureColumns() return metadata
                  for both procedures and functions as before, keeping
                  backward compatibility. Setting this property to
                  'false' decouples Connector/J from its pre-JDBC4
                  behaviours for DatabaseMetaData.getProcedures() and
                  DatabaseMetaData.getProcedureColumns(), forcing them
                  to return metadata for procedures only.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.26
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>ignoreNonTxTables</strong></span>
                </p>



                <p>
                  Ignore non-transactional table warning for rollback?
                  (defaults to 'false').
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.0.9
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>jdbcCompliantTruncation</strong></span>
                </p>



                <p>
                  Should the driver throw java.sql.DataTruncation
                  exceptions when data is truncated as is required by
                  the JDBC specification when connected to a server that
                  supports warnings (MySQL 4.1.0 and newer)? This
                  property has no effect if the server sql-mode includes
                  STRICT_TRANS_TABLES.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalanceAutoCommitStatementRegex</strong></span>
                </p>



                <p>
                  When load-balancing is enabled for auto-commit
                  statements (via
                  loadBalanceAutoCommitStatementThreshold), the
                  statement counter will only increment when the SQL
                  matches the regular expression. By default, every
                  statement issued matches.
                </p>



                <p>
                  Since version: 5.1.15
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalanceAutoCommitStatementThreshold</strong></span>
                </p>



                <p>
                  When auto-commit is enabled, the number of statements
                  which should be executed before triggering
                  load-balancing to rebalance. Default value of 0 causes
                  load-balanced connections to only rebalance when
                  exceptions are encountered, or auto-commit is disabled
                  and transactions are explicitly committed or rolled
                  back.
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 5.1.15
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalanceBlacklistTimeout</strong></span>
                </p>



                <p>
                  Time in milliseconds between checks of servers which
                  are unavailable, by controlling how long a server
                  lives in the global blacklist.
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 5.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalanceConnectionGroup</strong></span>
                </p>



                <p>
                  Logical group of load-balanced connections within a
                  classloader, used to manage different groups
                  independently. If not specified, live management of
                  load-balanced connections is disabled.
                </p>



                <p>
                  Since version: 5.1.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalanceExceptionChecker</strong></span>
                </p>



                <p>
                  Fully-qualified class name of custom exception
                  checker. The class must implement
                  com.mysql.jdbc.LoadBalanceExceptionChecker interface,
                  and is used to inspect SQLExceptions and determine
                  whether they should trigger fail-over to another host
                  in a load-balanced deployment.
                </p>



                <p>
                  Default:
                  com.mysql.jdbc.StandardLoadBalanceExceptionChecker
                </p>



                <p>
                  Since version: 5.1.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalancePingTimeout</strong></span>
                </p>



                <p>
                  Time in milliseconds to wait for ping response from
                  each of load-balanced physical connections when using
                  load-balanced Connection.
                </p>



                <p>
                  Default: 0
                </p>



                <p>
                  Since version: 5.1.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalanceSQLExceptionSubclassFailover</strong></span>
                </p>



                <p>
                  Comma-delimited list of classes/interfaces used by
                  default load-balanced exception checker to determine
                  whether a given SQLException should trigger failover.
                  The comparison is done using
                  Class.isInstance(SQLException) using the thrown
                  SQLException.
                </p>



                <p>
                  Since version: 5.1.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalanceSQLStateFailover</strong></span>
                </p>



                <p>
                  Comma-delimited list of SQLState codes used by default
                  load-balanced exception checker to determine whether a
                  given SQLException should trigger failover. The
                  SQLState of a given SQLException is evaluated to
                  determine whether it begins with any value in the
                  comma-delimited list.
                </p>



                <p>
                  Since version: 5.1.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>loadBalanceValidateConnectionOnSwapServer</strong></span>
                </p>



                <p>
                  Should the load-balanced Connection explicitly check
                  whether the connection is live when swapping to a new
                  physical connection at commit/rollback?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>maxRows</strong></span>
                </p>



                <p>
                  The maximum number of rows to return (0, the default
                  means return all rows).
                </p>



                <p>
                  Default: -1
                </p>



                <p>
                  Since version: all versions
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>netTimeoutForStreamingResults</strong></span>
                </p>



                <p>
                  What value should the driver automatically set the
                  server setting 'net_write_timeout' to when the
                  streaming result sets feature is in use? (value has
                  unit of seconds, the value '0' means the driver will
                  not try and adjust this value)
                </p>



                <p>
                  Default: 600
                </p>



                <p>
                  Since version: 5.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>noAccessToProcedureBodies</strong></span>
                </p>



                <p>
                  When determining procedure parameter types for
                  CallableStatements, and the connected user can't
                  access procedure bodies through "SHOW CREATE
                  PROCEDURE" or select on mysql.proc should the driver
                  instead create basic metadata (all parameters reported
                  as IN VARCHARs, but allowing registerOutParameter() to
                  be called on them anyway) instead of throwing an
                  exception?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>noDatetimeStringSync</strong></span>
                </p>



                <p>
                  Don't ensure that
                  ResultSet.getDatetimeType().toString().equals(ResultSet.getString())
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>noTimezoneConversionForDateType</strong></span>
                </p>



                <p>
                  Don't convert DATE values using the server time zone
                  if 'useTimezone'='true' or
                  'useLegacyDatetimeCode'='false'
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.35
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>noTimezoneConversionForTimeType</strong></span>
                </p>



                <p>
                  Don't convert TIME values using the server time zone
                  if 'useTimezone'='true'
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>nullCatalogMeansCurrent</strong></span>
                </p>



                <p>
                  When DatabaseMetadataMethods ask for a 'catalog'
                  parameter, does the value null mean use the current
                  catalog? (this is not JDBC-compliant, but follows
                  legacy behavior from earlier versions of the driver)
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.8
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>nullNamePatternMatchesAll</strong></span>
                </p>



                <p>
                  Should DatabaseMetaData methods that accept *pattern
                  parameters treat null the same as '%' (this is not
                  JDBC-compliant, however older versions of the driver
                  accepted this departure from the specification)
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.8
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>overrideSupportsIntegrityEnhancementFacility</strong></span>
                </p>



                <p>
                  Should the driver return "true" for
                  DatabaseMetaData.supportsIntegrityEnhancementFacility()
                  even if the database doesn't support it to workaround
                  applications that require this method to return "true"
                  to signal support of foreign keys, even though the SQL
                  specification states that this facility contains much
                  more than just foreign key support (one such
                  application being OpenOffice)?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.12
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>padCharsWithSpace</strong></span>
                </p>



                <p>
                  If a result set column has the CHAR type and the value
                  does not fill the amount of characters specified in
                  the DDL for the column, should the driver pad the
                  remaining characters with space (for ANSI compliance)?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>pedantic</strong></span>
                </p>



                <p>
                  Follow the JDBC spec to the letter.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.0.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>pinGlobalTxToPhysicalConnection</strong></span>
                </p>



                <p>
                  When using XAConnections, should the driver ensure
                  that operations on a given XID are always routed to
                  the same physical connection? This allows the
                  XAConnection to support "XA START ... JOIN" after "XA
                  END" has been called
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>populateInsertRowWithDefaultValues</strong></span>
                </p>



                <p>
                  When using ResultSets that are CONCUR_UPDATABLE,
                  should the driver pre-populate the "insert" row with
                  default values from the DDL for the table used in the
                  query so those values are immediately available for
                  ResultSet accessors? This functionality requires a
                  call to the database for metadata each time a result
                  set of this type is created. If disabled (the
                  default), the default values will be populated by the
                  an internal call to refreshRow() which pulls back
                  default values and/or values changed by triggers.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>processEscapeCodesForPrepStmts</strong></span>
                </p>



                <p>
                  Should the driver process escape codes in queries that
                  are prepared? Default escape processing behavior in
                  non-prepared statements must be defined with the
                  property 'enableEscapeProcessing'.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.12
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>queryTimeoutKillsConnection</strong></span>
                </p>



                <p>
                  If the timeout given in Statement.setQueryTimeout()
                  expires, should the driver forcibly abort the
                  Connection instead of attempting to abort the query?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.9
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>relaxAutoCommit</strong></span>
                </p>



                <p>
                  If the version of MySQL the driver connects to does
                  not support transactions, still allow calls to
                  commit(), rollback() and setAutoCommit() (true/false,
                  defaults to 'false')?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 2.0.13
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>retainStatementAfterResultSetClose</strong></span>
                </p>



                <p>
                  Should the driver retain the Statement reference in a
                  ResultSet after ResultSet.close() has been called.
                  This is not JDBC-compliant after JDBC-4.0.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.11
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>rollbackOnPooledClose</strong></span>
                </p>



                <p>
                  Should the driver issue a rollback() when the logical
                  connection in a pool is closed?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.0.15
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>runningCTS13</strong></span>
                </p>



                <p>
                  Enables workarounds for bugs in Sun's JDBC compliance
                  testsuite version 1.3
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>sendFractionalSeconds</strong></span>
                </p>



                <p>
                  Send fractional part from TIMESTAMP seconds. If set to
                  false, the nanoseconds value of TIMESTAMP values will
                  be truncated before sending any data to the server.
                  This option applies only to prepared statements,
                  callable statements or updatable result sets.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.37
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>serverTimezone</strong></span>
                </p>



                <p>
                  Override detection/mapping of time zone. Used when
                  time zone from server doesn't map to Java time zone
                </p>



                <p>
                  Since version: 3.0.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>statementInterceptors</strong></span>
                </p>



                <p>
                  A comma-delimited list of classes that implement
                  "com.mysql.jdbc.StatementInterceptor" that should be
                  placed "in between" query execution to influence the
                  results. StatementInterceptors are "chainable", the
                  results returned by the "current" interceptor will be
                  passed on to the next in in the chain, from
                  left-to-right order, as specified in this property.
                </p>



                <p>
                  Since version: 5.1.1
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>strictFloatingPoint</strong></span>
                </p>



                <p>
                  Used only in older versions of compliance test
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.0.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>strictUpdates</strong></span>
                </p>



                <p>
                  Should the driver do strict checking (all primary keys
                  selected) of updatable result sets (true, false,
                  defaults to 'true')?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.0.4
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>tinyInt1isBit</strong></span>
                </p>



                <p>
                  Should the driver treat the datatype TINYINT(1) as the
                  BIT type (because the server silently converts BIT
                  -&gt; TINYINT(1) when creating tables)?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.0.16
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>transformedBitIsBoolean</strong></span>
                </p>



                <p>
                  If the driver converts TINYINT(1) to a different type,
                  should it use BOOLEAN instead of BIT for future
                  compatibility with MySQL-5.0, as MySQL-5.0 has a BIT
                  type?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.9
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>treatUtilDateAsTimestamp</strong></span>
                </p>



                <p>
                  Should the driver treat java.util.Date as a TIMESTAMP
                  for the purposes of PreparedStatement.setObject()?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.0.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>ultraDevHack</strong></span>
                </p>



                <p>
                  Create PreparedStatements for prepareCall() when
                  required, because UltraDev is broken and issues a
                  prepareCall() for _all_ statements? (true/false,
                  defaults to 'false')
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 2.0.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useAffectedRows</strong></span>
                </p>



                <p>
                  Don't set the CLIENT_FOUND_ROWS flag when connecting
                  to the server (not JDBC-compliant, will break most
                  applications that rely on "found" rows vs. "affected
                  rows" for DML statements), but does cause "correct"
                  update counts from "INSERT ... ON DUPLICATE KEY
                  UPDATE" statements to be returned by the server.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.1.7
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useGmtMillisForDatetimes</strong></span>
                </p>



                <p>
                  Convert between session time zone and GMT before
                  creating Date and Timestamp instances (value of
                  'false' leads to legacy behavior, 'true' leads to more
                  JDBC-compliant behavior)? This is part of the legacy
                  date-time code, thus the property has an effect only
                  when "useLegacyDatetimeCode=true."
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.12
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useHostsInPrivileges</strong></span>
                </p>



                <p>
                  Add '@hostname' to users in
                  DatabaseMetaData.getColumn/TablePrivileges()
                  (true/false), defaults to 'true'.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.0.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useInformationSchema</strong></span>
                </p>



                <p>
                  When connected to MySQL-5.0.7 or newer, should the
                  driver use the INFORMATION_SCHEMA to derive
                  information used by DatabaseMetaData?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useJDBCCompliantTimezoneShift</strong></span>
                </p>



                <p>
                  Should the driver use JDBC-compliant rules when
                  converting TIME/TIMESTAMP/DATETIME values' time zone
                  information for those JDBC arguments which take a
                  java.util.Calendar argument? This is part of the
                  legacy date-time code, thus the property has an effect
                  only when "useLegacyDatetimeCode=true."
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useLegacyDatetimeCode</strong></span>
                </p>



                <p>
                  Use code for DATE/TIME/DATETIME/TIMESTAMP handling in
                  result sets and statements that consistently handles
                  time zone conversions from client to server and back
                  again, or use the legacy code for these datatypes that
                  has been in the driver for backwards-compatibility?
                  Setting this property to 'false' voids the effects of
                  "useTimezone," "useJDBCCompliantTimezoneShift,"
                  "useGmtMillisForDatetimes," and "useFastDateParsing."
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 5.1.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useOldAliasMetadataBehavior</strong></span>
                </p>



                <p>
                  Should the driver use the legacy behavior for "AS"
                  clauses on columns and tables, and only return aliases
                  (if any) for ResultSetMetaData.getColumnName() or
                  ResultSetMetaData.getTableName() rather than the
                  original column/table name? In 5.0.x, the default
                  value was true.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.4
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useOldUTF8Behavior</strong></span>
                </p>



                <p>
                  Use the UTF-8 behavior the driver did when
                  communicating with 4.0 and older servers
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.6
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useOnlyServerErrorMessages</strong></span>
                </p>



                <p>
                  Don't prepend 'standard' SQLState error messages to
                  error messages returned by the server.
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.0.15
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useSSPSCompatibleTimezoneShift</strong></span>
                </p>



                <p>
                  If migrating from an environment that was using
                  server-side prepared statements, and the configuration
                  property "useJDBCCompliantTimeZoneShift" set to
                  "true", use compatible behavior when not using
                  server-side prepared statements when sending TIMESTAMP
                  values to the MySQL server.
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 5.0.5
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useServerPrepStmts</strong></span>
                </p>



                <p>
                  Use server-side prepared statements if the server
                  supports them?
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.1.0
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useSqlStateCodes</strong></span>
                </p>



                <p>
                  Use SQL Standard state codes instead of 'legacy'
                  X/Open/SQL state codes (true/false), default is 'true'
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.3
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useStreamLengthsInPrepStmts</strong></span>
                </p>



                <p>
                  Honor stream length parameter in
                  PreparedStatement/ResultSet.setXXXStream() method
                  calls (true/false, defaults to 'true')?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.0.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useTimezone</strong></span>
                </p>



                <p>
                  Convert time/date types between client and server time
                  zones (true/false, defaults to 'false')? This is part
                  of the legacy date-time code, thus the property has an
                  effect only when "useLegacyDatetimeCode=true."
                </p>



                <p>
                  Default: false
                </p>



                <p>
                  Since version: 3.0.2
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>useUnbufferedInput</strong></span>
                </p>



                <p>
                  Don't use BufferedInputStream for reading data from
                  the server
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.0.11
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>yearIsDateType</strong></span>
                </p>



                <p>
                  Should the JDBC driver treat the MySQL type "YEAR" as
                  a java.sql.Date, or as a SHORT?
                </p>



                <p>
                  Default: true
                </p>



                <p>
                  Since version: 3.1.9
                </p></td></tr><tr><td scope="row"><p>
                  <span class="strong"><strong>zeroDateTimeBehavior</strong></span>
                </p>



                <p>
                  What should happen when the driver encounters DATETIME
                  values that are composed entirely of zeros (used by
                  MySQL to represent invalid dates)? Valid values are
                  "exception", "round" and "convertToNull".
                </p>



                <p>
                  Default: exception
                </p>



                <p>
                  Since version: 3.1.4
                </p></td></tr></tbody></table></div><p>
    </p><p>
        Connector/J also supports access to MySQL using named pipes on
        Windows platforms with the
        <code class="literal">NamedPipeSocketFactory</code> as a plugin-socket
        factory. If you do not use a <code class="literal">namedPipePath</code>
        property, the default of <code class="literal">'\\.\pipe\MySQL'</code> is
        used. If you use the <code class="literal">NamedPipeSocketFactory</code>,
        the host name and port number values in the JDBC URL are
        ignored. To enable this feature, set the
        <code class="literal">socketFactory</code> property:

</p><pre class="programlisting">
socketFactory=com.mysql.jdbc.NamedPipeSocketFactory
</pre><p>
      </p><p>
        Named pipes only work when connecting to a MySQL server on the
        same physical machine where the JDBC driver is running. In
        simple performance tests, named pipe access is between 30%-50%
        faster than the standard TCP/IP access. However, this varies per
        system, and named pipes are slower than TCP/IP in many Windows
        configurations.
      </p><p>
        To create your own socket factories, follow the example code in
        <code class="classname">com.mysql.jdbc.NamedPipeSocketFactory</code>, or
        <code class="classname">com.mysql.jdbc.StandardSocketFactory</code>.
      </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-useconfigs"></a>5.1.1 Properties Files for the <code class="literal">useConfigs</code> Option</h3></div></div></div><a class="indexterm" name="idm140410758650640"></a><p>
          The <code class="literal">useConfigs</code> connection option is
          convenient shorthand for specifying combinations of options
          for particular scenarios. The argument values you can use with
          this option correspond to the names of
          <code class="filename">.properties</code> files within the Connector/J
          <code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar</code>
          JAR file. For example, the Connector/J 5.1.9 driver includes
          the following configuration properties files:
        </p><pre class="programlisting">
$ unzip mysql-connector-java-5.1.19-bin.jar '*/configs/*'
Archive:  mysql-connector-java-5.1.19-bin.jar
   creating: com/mysql/jdbc/configs/
  inflating: com/mysql/jdbc/configs/3-0-Compat.properties  
  inflating: com/mysql/jdbc/configs/5-0-Compat.properties  
  inflating: com/mysql/jdbc/configs/clusterBase.properties  
  inflating: com/mysql/jdbc/configs/coldFusion.properties  
  inflating: com/mysql/jdbc/configs/fullDebug.properties  
  inflating: com/mysql/jdbc/configs/maxPerformance.properties  
  inflating: com/mysql/jdbc/configs/solarisMaxPerformance.properties 
</pre><p>
          To specify one of these combinations of options, specify
          <code class="literal">useConfigs=3-0-Compat</code>,
          <code class="literal">useConfigs=maxPerformance</code>, and so on. The
          following sections show the options that are part of each
          <code class="literal">useConfigs</code> setting. For the details of why
          each one is included, see the comments in the
          <code class="filename">.properties</code> files.
        </p><h4><a name="idm140410758642176"></a>3-0-Compat</h4><pre class="programlisting">
emptyStringsConvertToZero=true
jdbcCompliantTruncation=false
noDatetimeStringSync=true
nullCatalogMeansCurrent=true
nullNamePatternMatchesAll=true
transformedBitIsBoolean=false
dontTrackOpenResources=true
zeroDateTimeBehavior=convertToNull
useServerPrepStmts=false
autoClosePStmtStreams=true
processEscapeCodesForPrepStmts=false
useFastDateParsing=false
populateInsertRowWithDefaultValues=false
useDirectRowUnpack=false
</pre><h4><a name="idm140410758640496"></a>5-0-Compat</h4><pre class="programlisting">
useDirectRowUnpack=false
</pre><h4><a name="idm140410758639248"></a>clusterBase</h4><pre class="programlisting">
autoReconnect=true
failOverReadOnly=false
roundRobinLoadBalance=true
</pre><h4><a name="idm140410758637920"></a>coldFusion</h4><pre class="programlisting">
useDynamicCharsetInfo=false
alwaysSendSetIsolation=false
useLocalSessionState=true
autoReconnect=true
</pre><h4><a name="idm140410758636560"></a>fullDebug</h4><pre class="programlisting">
profileSQL=true
gatherPerfMetrics=true
useUsageAdvisor=true
logSlowQueries=true
explainSlowQueries=true
</pre><h4><a name="idm140410758635184"></a>maxPerformance</h4><pre class="programlisting">
cachePrepStmts=true
cacheCallableStmts=true
cacheServerConfiguration=true
useLocalSessionState=true
elideSetAutoCommits=true
alwaysSendSetIsolation=false
enableQueryTimeouts=false
</pre><h4><a name="idm140410758633744"></a>solarisMaxPerformance</h4><pre class="programlisting">
useUnbufferedInput=false
useReadAheadInput=false
maintainTimeStats=false
</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-implementation-notes"></a>5.2 JDBC API Implementation Notes</h2></div></div></div><a class="indexterm" name="idm140410758631264"></a><p>
        MySQL Connector/J, as a rigorous implementation of the
        <a class="ulink" href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html" target="_top">JDBC
        API</a>, passes all of the tests in the publicly available
        version of Oracle's JDBC compliance test suite. The JDBC
        specification is flexible on how certain functionality should be
        implemented. This section gives details on an
        interface-by-interface level about implementation decisions that
        might affect how you code applications with MySQL Connector/J.
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <span class="bold"><strong>BLOB</strong></span>
          </p><p>
            Starting with Connector/J version 3.1.0, you can emulate
            BLOBs with locators by adding the property
            <code class="literal">emulateLocators=true</code> to your JDBC URL.
            Using this method, the driver will delay loading the actual
            BLOB data until you retrieve the other data and then use
            retrieval methods (<code class="function">getInputStream()</code>,
            <code class="function">getBytes()</code>, and so forth) on the BLOB
            data stream.
          </p><p>
            You must use a column alias with the value of the column to
            the actual name of the BLOB, for example:
          </p><pre class="programlisting">
SELECT id, 'data' as blob_data from blobtable
</pre><p>
            You must also follow these rules:
          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                The <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> must reference
                only one table. The table must have a
                <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_primary_key" target="_top">primary key</a>.
              </p></li><li class="listitem"><p>
                The <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> must alias the
                original BLOB column name, specified as a string, to an
                alternate name.
              </p></li><li class="listitem"><p>
                The <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> must cover all
                columns that make up the primary key.
              </p></li></ul></div><p>
            The BLOB implementation does not allow in-place modification
            (they are copies, as reported by the
            <code class="literal">DatabaseMetaData.locatorsUpdateCopies()</code>
            method). Because of this, use the corresponding
            <code class="literal">PreparedStatement.setBlob()</code> or
            <code class="literal">ResultSet.updateBlob()</code> (in the case of
            updatable result sets) methods to save changes back to the
            database.
          </p></li><li class="listitem"><p>
            <span class="bold"><strong>CallableStatement</strong></span>
          </p><p>
            Starting with Connector/J 3.1.1, stored procedures are
            supported when connecting to MySQL version 5.0 or newer
            using the <code class="classname">CallableStatement</code>
            interface. Currently, the
            <code class="function">getParameterMetaData()</code> method of
            <code class="classname">CallableStatement</code> is not supported.
          </p></li><li class="listitem"><p>
            <span class="bold"><strong>CLOB</strong></span>
          </p><p>
            The CLOB implementation does not allow in-place modification
            (they are copies, as reported by the
            <code class="literal">DatabaseMetaData.locatorsUpdateCopies()</code>
            method). Because of this, use the
            <code class="literal">PreparedStatement.setClob()</code> method to
            save changes back to the database. The JDBC API does not
            have a <code class="literal">ResultSet.updateClob()</code> method.
          </p></li><li class="listitem"><p>
            <span class="bold"><strong>Connection</strong></span>
          </p><p>
            Unlike the pre-Connector/J JDBC driver
            (<code class="literal">MM.MySQL</code>), the
            <code class="function">isClosed()</code> method does not ping the
            server to determine if it is available. In accordance with
            the JDBC specification, it only returns true if
            <code class="function">closed()</code> has been called on the
            connection. If you need to determine if the connection is
            still valid, issue a simple query, such as <code class="literal">SELECT
            1</code>. The driver will throw an exception if the
            connection is no longer valid.
          </p></li><li class="listitem"><p>
            <span class="bold"><strong>DatabaseMetaData</strong></span>
          </p><p>
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_foreign_key" target="_top">Foreign key</a>
            information
            (<code class="function">getImportedKeys()</code>/<code class="function">getExportedKeys()</code>
            and <code class="function">getCrossReference()</code>) is only
            available from <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/innodb-storage-engine.html" target="_top"><code class="literal">InnoDB</code></a> tables.
            The driver uses <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/show-create-table.html" target="_top"><code class="literal">SHOW CREATE
            TABLE</code></a> to retrieve this information, so if any
            other storage engines add support for foreign keys, the
            driver would transparently support them as well.
          </p></li><li class="listitem"><p>
            <span class="bold"><strong>PreparedStatement</strong></span>
          </p><p>
            PreparedStatements are implemented by the driver, as MySQL
            does not have a prepared statement feature. Because of this,
            the driver does not implement
            <code class="function">getParameterMetaData()</code> or
            <code class="function">getMetaData()</code> as it would require the
            driver to have a complete SQL parser in the client.
          </p><p>
            Starting with version 3.1.0 MySQL Connector/J, server-side
            prepared statements and binary-encoded result sets are used
            when the server supports them.
          </p><p>
            Take care when using a server-side prepared statement with
            <span class="bold"><strong>large</strong></span> parameters that are
            set using <code class="function">setBinaryStream()</code>,
            <code class="function">setAsciiStream()</code>,
            <code class="function">setUnicodeStream()</code>,
            <code class="function">setBlob()</code>, or
            <code class="function">setClob()</code>. To re-execute the statement
            with any large parameter changed to a nonlarge parameter,
            call <code class="function">clearParameters()</code> and set all
            parameters again. The reason for this is as follows:
          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                During both server-side prepared statements and
                client-side emulation, large data is exchanged only when
                <code class="literal">PreparedStatement.execute()</code> is
                called.
              </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                Once that has been done, the stream used to read the
                data on the client side is closed (as per the JDBC
                spec), and cannot be read from again.
              </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                If a parameter changes from large to nonlarge, the
                driver must reset the server-side state of the prepared
                statement to allow the parameter that is being changed
                to take the place of the prior large value. This removes
                all of the large data that has already been sent to the
                server, thus requiring the data to be re-sent, using the
                <code class="function">setBinaryStream()</code>,
                <code class="function">setAsciiStream()</code>,
                <code class="function">setUnicodeStream()</code>,
                <code class="function">setBlob()</code> or
                <code class="function">setClob()</code> method.
              </p></li></ul></div><p>
            Consequently, to change the type of a parameter to a
            nonlarge one, you must call
            <code class="function">clearParameters()</code> and set all
            parameters of the prepared statement again before it can be
            re-executed.
          </p></li><li class="listitem"><p>
            <span class="bold"><strong>ResultSet</strong></span>
          </p><p>
            By default, ResultSets are completely retrieved and stored
            in memory. In most cases this is the most efficient way to
            operate and, due to the design of the MySQL network
            protocol, is easier to implement. If you are working with
            ResultSets that have a large number of rows or large values
            and cannot allocate heap space in your JVM for the memory
            required, you can tell the driver to stream the results back
            one row at a time.
          </p><p>
            To enable this functionality, create a
            <code class="literal">Statement</code> instance in the following
            manner:
          </p><pre class="programlisting">
stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
              java.sql.ResultSet.CONCUR_READ_ONLY);
stmt.setFetchSize(Integer.MIN_VALUE);
</pre><p>
            The combination of a forward-only, read-only result set,
            with a fetch size of <code class="literal">Integer.MIN_VALUE</code>
            serves as a signal to the driver to stream result sets
            row-by-row. After this, any result sets created with the
            statement will be retrieved row-by-row.
          </p><p>
            There are some caveats with this approach. You must read all
            of the rows in the result set (or close it) before you can
            issue any other queries on the connection, or an exception
            will be thrown.
          </p><p>
            The earliest the locks these statements hold can be released
            (whether they be <code class="literal">MyISAM</code> table-level locks
            or row-level locks in some other storage engine such as
            <code class="literal">InnoDB</code>) is when the statement completes.
          </p><p>
            If the statement is within scope of a transaction, then
            locks are released when the transaction completes (which
            implies that the statement needs to complete first). As with
            most other databases, statements are not complete until all
            the results pending on the statement are read or the active
            result set for the statement is closed.
          </p><p>
            Therefore, if using streaming results, process them as
            quickly as possible if you want to maintain concurrent
            access to the tables referenced by the statement producing
            the result set.
          </p></li><li class="listitem"><p>
            <span class="bold"><strong>ResultSetMetaData</strong></span>
          </p><p>
            The <code class="function">isAutoIncrement()</code> method only works
            when using MySQL servers 4.0 and newer.
          </p></li><li class="listitem"><p>
            <span class="bold"><strong>Statement</strong></span>
          </p><p>
            When using versions of the JDBC driver earlier than 3.2.1,
            and connected to server versions earlier than 5.0.3, the
            <code class="function">setFetchSize()</code> method has no effect,
            other than to toggle result set streaming as described
            above.
          </p><p>
            Connector/J 5.0.0 and later include support for both
            <code class="literal">Statement.cancel()</code> and
            <code class="literal">Statement.setQueryTimeout()</code>. Both require
            MySQL 5.0.0 or newer server, and require a separate
            connection to issue the
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/kill.html" target="_top"><code class="literal">KILL QUERY</code></a>
            statement. In the case of
            <code class="function">setQueryTimeout()</code>, the implementation
            creates an additional thread to handle the timeout
            functionality.
          </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
              Failures to cancel the statement for
              <code class="function">setQueryTimeout()</code> may manifest
              themselves as <code class="literal">RuntimeException</code> rather
              than failing silently, as there is currently no way to
              unblock the thread that is executing the query being
              cancelled due to timeout expiration and have it throw the
              exception instead.
            </p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
              The MySQL statement
              <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/kill.html" target="_top"><code class="literal">KILL QUERY</code></a>
              (which is what the driver uses to implement
              <code class="literal">Statement.cancel()</code>) is
              non-deterministic; thus, avoid the use of
              <code class="literal">Statement.cancel()</code> if possible. If no
              query is in process, the next query issued will be killed
              by the server. This race condition is guarded against as
              of Connector/J 5.1.18.
            </p></div><p>
            MySQL does not support SQL cursors, and the JDBC driver
            doesn't emulate them, so <code class="literal">setCursorName()</code>
            has no effect.
          </p><p>
            Connector/J 5.1.3 and later include two additional methods:
          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="function">setLocalInfileInputStream()</code> sets an
                <code class="literal">InputStream</code> instance that will be
                used to send data to the MySQL server for a
                <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/load-data.html" target="_top"><code class="literal">LOAD DATA
                LOCAL INFILE</code></a> statement rather than a
                <code class="literal">FileInputStream</code> or
                <code class="literal">URLInputStream</code> that represents the
                path given as an argument to the statement.
              </p><p>
                This stream will be read to completion upon execution of
                a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/load-data.html" target="_top"><code class="literal">LOAD DATA
                LOCAL INFILE</code></a> statement, and will automatically
                be closed by the driver, so it needs to be reset before
                each call to <code class="literal">execute*()</code> that would
                cause the MySQL server to request data to fulfill the
                request for
                <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/load-data.html" target="_top"><code class="literal">LOAD DATA
                LOCAL INFILE</code></a>.
              </p><p>
                If this value is set to <code class="literal">NULL</code>, the
                driver will revert to using a
                <code class="literal">FileInputStream</code> or
                <code class="literal">URLInputStream</code> as required.
              </p></li><li class="listitem"><p>
                <code class="function">getLocalInfileInputStream()</code> returns
                the <code class="literal">InputStream</code> instance that will be
                used to send data in response to a
                <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/load-data.html" target="_top"><code class="literal">LOAD DATA
                LOCAL INFILE</code></a> statement.
              </p><p>
                This method returns <code class="literal">NULL</code> if no such
                stream has been set using
                <code class="function">setLocalInfileInputStream()</code>.
              </p></li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-type-conversions"></a>5.3 Java, JDBC and MySQL Types</h2></div></div></div><a class="indexterm" name="idm140410758533344"></a><p>
        MySQL Connector/J is flexible in the way it handles conversions
        between MySQL data types and Java data types.
      </p><p>
        In general, any MySQL data type can be converted to a
        <code class="literal">java.lang.String</code>, and any numeric type can be
        converted to any of the Java numeric types, although round-off,
        overflow, or loss of precision may occur.
      </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
          All <code class="literal">TEXT</code> types return
          <code class="literal">Types.LONGVARCHAR</code> with different
          <code class="literal">getPrecision()</code> values (65535, 255,
          16777215, and 2147483647 respectively) with
          <code class="literal">getColumnType()</code> returning
          <code class="literal">-1</code>. This behavior is intentional even
          though <code class="literal">TINYTEXT</code> does not fall, regarding to
          its size, within the <code class="literal">LONGVARCHAR</code> category.
          This is to avoid different handling inside the same base type.
          And <code class="literal">getColumnType()</code> returns
          <code class="literal">-1</code> because the internal server handling is
          of type <code class="literal">TEXT</code>, which is similar to
          <code class="literal">BLOB</code>.
        </p><p>
          Also note that <code class="literal">getColumnTypeName()</code> will
          return <code class="literal">VARCHAR</code> even though
          <code class="literal">getColumnType()</code> returns
          <code class="literal">Types.LONGVARCHAR</code>, because
          <code class="literal">VARCHAR</code> is the designated column
          database-specific name for this type.
        </p></div><p>
        Starting with Connector/J 3.1.0, the JDBC driver issues warnings
        or throws <code class="literal">DataTruncation</code> exceptions as is
        required by the JDBC specification unless the connection was
        configured not to do so by using the property
        <code class="literal">jdbcCompliantTruncation</code> and setting it to
        <code class="literal">false</code>.
      </p><p>
        The conversions that are always guaranteed to work are listed in
        the following table. The first column lists one or more MySQL
        data types, and the second column lists one or more Java types
        to which the MySQL types can be converted.
      </p><div class="table"><a name="idm140410758514976"></a><p class="title"><b>Table 5.1 Connection Properties - Miscellaneous</b></p><div class="table-contents"><table summary="Connection Properties - Miscellaneous" border="1"><colgroup><col><col></colgroup><thead><tr><th scope="col">These MySQL Data Types</th><th scope="col">Can always be converted to these Java types</th></tr></thead><tbody><tr><td scope="row"><code class="literal">CHAR, VARCHAR, BLOB, TEXT, ENUM, and SET</code></td><td><code class="literal">java.lang.String, java.io.InputStream, java.io.Reader,
                java.sql.Blob, java.sql.Clob</code></td></tr><tr><td scope="row"><code class="literal">FLOAT, REAL, DOUBLE PRECISION, NUMERIC, DECIMAL, TINYINT,
                SMALLINT, MEDIUMINT, INTEGER, BIGINT</code></td><td><code class="literal">java.lang.String, java.lang.Short, java.lang.Integer,
                java.lang.Long, java.lang.Double,
                java.math.BigDecimal</code></td></tr><tr><td scope="row"><code class="literal">DATE, TIME, DATETIME, TIMESTAMP</code></td><td><code class="literal">java.lang.String, java.sql.Date, java.sql.Timestamp</code></td></tr></tbody></table></div></div><br class="table-break"><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
          Round-off, overflow or loss of precision may occur if you
          choose a Java numeric data type that has less precision or
          capacity than the MySQL data type you are converting to/from.
        </p></div><p>
        The <code class="classname">ResultSet.getObject()</code> method uses the
        type conversions between MySQL and Java types, following the
        JDBC specification where appropriate. The value returned by
        <code class="classname">ResultSetMetaData.GetColumnClassName()</code> is
        also shown below. For more information on the JDBC types, see
        the reference on the
        <a class="ulink" href="http://docs.oracle.com/javase/8/docs/api/java/sql/Types.html" target="_top">java.sql.Types</a>
        class.
      </p><div class="table"><a name="idm140410758501440"></a><p class="title"><b>Table 5.2 MySQL Types to Java Types for ResultSet.getObject()</b></p><div class="table-contents"><table summary="MySQL Types to Java Types for ResultSet.getObject()" border="1"><colgroup><col><col><col></colgroup><thead><tr><th scope="col">MySQL Type Name</th><th scope="col">Return value of <code class="literal">GetColumnClassName</code></th><th scope="col">Returned as Java Class</th></tr></thead><tbody><tr><td scope="row"><code class="literal">BIT(1)</code> (new in MySQL-5.0)</td><td><code class="literal">BIT</code></td><td><code class="classname">java.lang.Boolean</code></td></tr><tr><td scope="row"><code class="literal">BIT( &gt; 1)</code> (new in MySQL-5.0)</td><td><code class="literal">BIT</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TINYINT</code></td><td><code class="literal">TINYINT</code></td><td><code class="classname">java.lang.Boolean</code> if the configuration property
                <code class="literal">tinyInt1isBit</code> is set to
                <code class="literal">true</code> (the default) and the storage
                size is 1, or <code class="classname">java.lang.Integer</code>
                if not.</td></tr><tr><td scope="row"><code class="literal">BOOL</code>, <code class="literal">BOOLEAN</code></td><td><code class="literal">TINYINT</code></td><td>See <code class="literal">TINYINT</code>, above as these are aliases for
                <code class="literal">TINYINT(1)</code>, currently.</td></tr><tr><td scope="row"><code class="literal">SMALLINT[(M)] [UNSIGNED]</code></td><td><code class="literal">SMALLINT [UNSIGNED]</code></td><td><code class="classname">java.lang.Integer</code> (regardless if
                <code class="literal">UNSIGNED</code> or not)</td></tr><tr><td scope="row"><code class="literal">MEDIUMINT[(M)] [UNSIGNED]</code></td><td><code class="literal">MEDIUMINT [UNSIGNED]</code></td><td><code class="classname">java.lang.Integer,</code> if <code class="literal">UNSIGNED</code>
                <code class="classname">java.lang.Long</code> (C/J 3.1 and
                earlier), or <code class="classname">java.lang.Integer</code>
                for C/J 5.0 and later</td></tr><tr><td scope="row"><code class="literal">INT,INTEGER[(M)] [UNSIGNED]</code></td><td><code class="literal">INTEGER [UNSIGNED]</code></td><td><code class="classname">java.lang.Integer</code>, if <code class="literal">UNSIGNED</code>
                <code class="classname">java.lang.Long</code></td></tr><tr><td scope="row"><code class="literal">BIGINT[(M)] [UNSIGNED]</code></td><td><code class="literal">BIGINT [UNSIGNED]</code></td><td><code class="classname">java.lang.Long</code>, if UNSIGNED
                <code class="classname">java.math.BigInteger</code></td></tr><tr><td scope="row"><code class="literal">FLOAT[(M,D)]</code></td><td><code class="literal">FLOAT</code></td><td><code class="classname">java.lang.Float</code></td></tr><tr><td scope="row"><code class="literal">DOUBLE[(M,B)]</code></td><td><code class="literal">DOUBLE</code></td><td><code class="classname">java.lang.Double</code></td></tr><tr><td scope="row"><code class="literal">DECIMAL[(M[,D])]</code></td><td><code class="literal">DECIMAL</code></td><td><code class="classname">java.math.BigDecimal</code></td></tr><tr><td scope="row"><code class="literal">DATE</code></td><td><code class="literal">DATE</code></td><td><code class="classname">java.sql.Date</code></td></tr><tr><td scope="row"><code class="literal">DATETIME</code></td><td><code class="literal">DATETIME</code></td><td><code class="classname">java.sql.Timestamp</code></td></tr><tr><td scope="row"><code class="literal">TIMESTAMP[(M)]</code></td><td><code class="literal">TIMESTAMP</code></td><td><code class="classname">java.sql.Timestamp</code></td></tr><tr><td scope="row"><code class="literal">TIME</code></td><td><code class="literal">TIME</code></td><td><code class="classname">java.sql.Time</code></td></tr><tr><td scope="row"><code class="literal">YEAR[(2|4)]</code></td><td><code class="literal">YEAR</code></td><td>If <code class="literal">yearIsDateType</code> configuration property is set to
                <code class="literal">false</code>, then the returned object type
                is <code class="classname">java.sql.Short</code>. If set to
                <code class="literal">true</code> (the default), then the returned
                object is of type <code class="classname">java.sql.Date</code>
                with the date


                set to January 1st, at midnight.</td></tr><tr><td scope="row"><code class="literal">CHAR(M)</code></td><td><code class="literal">CHAR</code></td><td><code class="classname">java.lang.String</code> (unless the character set for
                the column is <code class="literal">BINARY</code>, then
                <code class="classname">byte[]</code> is returned.</td></tr><tr><td scope="row"><code class="literal">VARCHAR(M) [BINARY]</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code> (unless the character set for
                the column is <code class="literal">BINARY</code>, then
                <code class="classname">byte[]</code> is returned.</td></tr><tr><td scope="row"><code class="literal">BINARY(M)</code></td><td><code class="literal">BINARY</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">VARBINARY(M)</code></td><td><code class="literal">VARBINARY</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TINYBLOB</code></td><td><code class="literal">TINYBLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TINYTEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">BLOB</code></td><td><code class="literal">BLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">MEDIUMBLOB</code></td><td><code class="literal">MEDIUMBLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">MEDIUMTEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">LONGBLOB</code></td><td><code class="literal">LONGBLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">LONGTEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">ENUM('value1','value2',...)</code></td><td><code class="literal">CHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">SET('value1','value2',...)</code></td><td><code class="literal">CHAR</code></td><td><code class="classname">java.lang.String</code></td></tr></tbody></table></div></div><br class="table-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-charsets"></a>5.4 Using Character Sets and Unicode</h2></div></div></div><a class="indexterm" name="idm140410758410128"></a><a class="indexterm" name="idm140410758408736"></a><a class="indexterm" name="idm140410758407344"></a><p>
        All strings sent from the JDBC driver to the server are
        converted automatically from native Java Unicode form to the
        client character encoding, including all queries sent using
        <code class="literal">Statement.execute()</code>,
        <code class="literal">Statement.executeUpdate()</code>,
        <code class="literal">Statement.executeQuery()</code> as well as all
        <code class="interfacename">PreparedStatement</code> and
        <code class="interfacename">CallableStatement</code> parameters with
        the exclusion of parameters set using
        <code class="function">setBytes()</code>,
        <code class="function">setBinaryStream()</code>,
        <code class="function">setAsciiStream()</code>,
        <code class="function">setUnicodeStream()</code> and
        <code class="function">setBlob()</code>.
      </p><h3><a name="idm140410758399504"></a>Number of Encodings Per Connection</h3><p>
        In MySQL Server 4.1 and higher, Connector/J supports a single
        character encoding between client and server, and any number of
        character encodings for data returned by the server to the
        client in <code class="classname">ResultSets</code>.
      </p><p>
        Prior to MySQL Server 4.1, Connector/J supported a single
        character encoding per connection, which could either be
        automatically detected from the server configuration, or could
        be configured by the user through the
        <em class="parameter"><code>useUnicode</code></em> and
        <em class="parameter"><code>characterEncoding</code></em> properties.
      </p><h3><a name="idm140410758395968"></a>Setting the Character Encoding</h3><p>
        The character encoding between client and server is
        automatically detected upon connection. You specify the encoding
        on the server using the
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html#sysvar_character_set_server" target="_top"><code class="literal">character_set_server</code></a> for server
        versions 4.1.0 and newer, and <code class="literal">character_set</code>
        system variable for server versions older than 4.1.0. The driver
        automatically uses the encoding specified by the server. For
        more information, see <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/charset-server.html" target="_top">Server Character Set and Collation</a>.
      </p><p>
        For example, to use 4-byte UTF-8 character sets with
        Connector/J, configure the MySQL server with
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html#sysvar_character_set_server" target="_top"><code class="literal">character_set_server=utf8mb4</code></a>,
        and leave <code class="literal">characterEncoding</code> out of the
        Connector/J connection string. Connector/J will then autodetect
        the UTF-8 setting.
      </p><p>
        To override the automatically detected encoding on the client
        side, use the <em class="parameter"><code>characterEncoding</code></em> property
        in the URL used to connect to the server.
      </p><p>
        To allow multiple character sets to be sent from the client, use
        the UTF-8 encoding, either by configuring
        <code class="literal">utf8</code> as the default server character set, or
        by configuring the JDBC driver to use UTF-8 through the
        <code class="literal">characterEncoding</code> property.
      </p><p>
        When specifying character encodings on the client side, use
        Java-style names. The following table lists MySQL character set
        names and the corresponding Java-style names:
      </p><div class="table"><a name="idm140410758386048"></a><p class="title"><b>Table 5.3 MySQL to Java Encoding Name Translations</b></p><div class="table-contents"><table summary="MySQL to Java Encoding Name Translations" border="1"><colgroup><col><col></colgroup><thead><tr><th scope="col">MySQL Character Set Name</th><th scope="col">Java-Style Character Encoding Name</th></tr></thead><tbody><tr><td scope="row"><code class="literal">ascii</code></td><td><code class="literal">US-ASCII</code></td></tr><tr><td scope="row"><code class="literal">big5</code></td><td><code class="literal">Big5</code></td></tr><tr><td scope="row"><code class="literal">gbk</code></td><td><code class="literal">GBK</code></td></tr><tr><td scope="row"><code class="literal">sjis</code></td><td><code class="literal">SJIS (or Cp932 or MS932 for MySQL Server &lt; 4.1.11)</code></td></tr><tr><td scope="row"><code class="literal">cp932</code></td><td><code class="literal">Cp932 or MS932 (MySQL Server &gt; 4.1.11)</code></td></tr><tr><td scope="row"><code class="literal">gb2312</code></td><td><code class="literal">EUC_CN</code></td></tr><tr><td scope="row"><code class="literal">ujis</code></td><td><code class="literal">EUC_JP</code></td></tr><tr><td scope="row"><code class="literal">euckr</code></td><td><code class="literal">EUC_KR</code></td></tr><tr><td scope="row"><code class="literal">latin1</code></td><td><code class="literal">Cp1252</code></td></tr><tr><td scope="row"><code class="literal">latin2</code></td><td><code class="literal">ISO8859_2</code></td></tr><tr><td scope="row"><code class="literal">greek</code></td><td><code class="literal">ISO8859_7</code></td></tr><tr><td scope="row"><code class="literal">hebrew</code></td><td><code class="literal">ISO8859_8</code></td></tr><tr><td scope="row"><code class="literal">cp866</code></td><td><code class="literal">Cp866</code></td></tr><tr><td scope="row"><code class="literal">tis620</code></td><td><code class="literal">TIS620</code></td></tr><tr><td scope="row"><code class="literal">cp1250</code></td><td><code class="literal">Cp1250</code></td></tr><tr><td scope="row"><code class="literal">cp1251</code></td><td><code class="literal">Cp1251</code></td></tr><tr><td scope="row"><code class="literal">cp1257</code></td><td><code class="literal">Cp1257</code></td></tr><tr><td scope="row"><code class="literal">macroman</code></td><td><code class="literal">MacRoman</code></td></tr><tr><td scope="row"><code class="literal">macce</code></td><td><code class="literal">MacCentralEurope</code></td></tr><tr><td scope="row"><code class="literal">utf8</code></td><td><code class="literal">UTF-8</code></td></tr><tr><td scope="row"><code class="literal">ucs2</code></td><td><code class="literal">UnicodeBig</code></td></tr></tbody></table></div></div><br class="table-break"><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Warning</div><p>
          Do not issue the query <code class="literal">set names</code> with
          Connector/J, as the driver will not detect that the character
          set has changed, and will continue to use the character set
          detected during the initial connection setup.
        </p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-using-ssl"></a>5.5 Connecting Securely Using SSL</h2></div></div></div><a class="indexterm" name="idm140410758339296"></a><p>
        SSL in MySQL Connector/J encrypts all data (other than the
        initial handshake) between the JDBC driver and the server. There
        is a performance penalty for enabling SSL, the severity of which
        depends on multiple factors including (but not limited to) the
        size of the query, the amount of data returned, the server
        hardware, the SSL library used, the network bandwidth, and so
        on.
      </p><p>
        For SSL support to work, you must have the following:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A JDK that includes JSSE (Java Secure Sockets Extension),
            like JDK-1.4.1 or newer. SSL does not currently work with a
            JDK that you can add JSSE to, like JDK-1.2.x or JDK-1.3.x
            due to the following JSSE bug:
            <a class="ulink" href="http://bugs.java.com/bugdatabase/view_bug.do?bug_id=4273544" target="_top">http://bugs.java.com/bugdatabase/view_bug.do?bug_id=4273544</a>
          </p></li><li class="listitem"><p>
            A MySQL server that supports SSL and has been compiled and
            configured to do so, which is MySQL 4.0.4 or later. For more
            information, see
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/building-with-ssl-support.html" target="_top">Building MySQL with SSL Support</a>.
          </p></li><li class="listitem"><p>
            A client certificate (covered later in this section)
          </p></li></ul></div><p>
        The system works through two Java truststore files, one file
        contains the certificate information for the server
        (<code class="filename">truststore</code> in the examples below). The
        other file contains the certificate for the client
        (<code class="filename">keystore</code> in the examples below). All Java
        truststore files are password protected by supplying a suitable
        password to the <span class="command"><strong>keytool</strong></span> when you create the
        files. You need the file names and associated passwords to
        create an SSL connection.
      </p><p>
        You will first need to import the MySQL server CA Certificate
        into a Java truststore. A sample MySQL server CA Certificate is
        located in the <code class="filename">SSL</code> subdirectory of the
        MySQL source distribution. This is what SSL will use to
        determine if you are communicating with a secure MySQL server.
        Alternatively, use the CA Certificate that you have generated or
        been provided with by your SSL provider.
      </p><p>
        To use Java's <span class="command"><strong>keytool</strong></span> to create a truststore
        in the current directory , and import the server's CA
        certificate (<code class="filename">cacert.pem</code>), you can do the
        following (assuming that <span class="command"><strong>keytool</strong></span> is in your
        path. The <span class="command"><strong>keytool</strong></span> is typically located in the
        <code class="filename">bin</code> subdirectory of your JDK or JRE):
      </p><pre class="programlisting">
shell&gt; keytool -import -alias mysqlServerCACert \
         -file cacert.pem -keystore truststore
</pre><p>
        Enter the password when prompted for the keystore file.
        Interaction with <span class="command"><strong>keytool</strong></span> looks like this:
      </p><pre class="programlisting">
Enter keystore password:  *********
Owner: EMAILADDRESS=walrus@example.com, CN=Walrus,
       O=MySQL AB, L=Orenburg, ST=Some-State, C=RU
Issuer: EMAILADDRESS=walrus@example.com, CN=Walrus,
       O=MySQL AB, L=Orenburg, ST=Some-State, C=RU
Serial number: 0
Valid from:
   Fri Aug 02 16:55:53 CDT 2002 until: Sat Aug 02 16:55:53 CDT 2003
Certificate fingerprints:
    MD5:  61:91:A0:F2:03:07:61:7A:81:38:66:DA:19:C4:8D:AB
    SHA1: 25:77:41:05:D5:AD:99:8C:14:8C:CA:68:9C:2F:B8:89:C3:34:4D:6C
Trust this certificate? [no]:  yes
Certificate was added to keystore
</pre><p>
        You then have two options: either import the client certificate
        that matches the CA certificate you just imported, or create a
        new client certificate.
      </p><p>
        Importing an existing certificate requires the certificate to be
        in DER format. You can use <span class="command"><strong>openssl</strong></span> to convert
        an existing certificate into the new format. For example:
      </p><pre class="programlisting">
shell&gt; openssl x509 -outform DER -in client-cert.pem -out client.cert
</pre><p>
        Now import the converted certificate into your keystore using
        <span class="command"><strong>keytool</strong></span>:
      </p><pre class="programlisting">
shell&gt; keytool -import -file client.cert -keystore keystore -alias mysqlClientCertificate
</pre><p>
        To generate your own client certificate, use
        <span class="command"><strong>keytool</strong></span> to create a suitable certificate and
        add it to the <code class="filename">keystore</code> file:
      </p><pre class="programlisting">
shell&gt; keytool -genkey -keyalg rsa \
     -alias mysqlClientCertificate -keystore keystore 
</pre><p>
        Keytool will prompt you for the following information, and
        create a keystore named <code class="filename">keystore</code> in the
        current directory.
      </p><p>
        Respond with information that is appropriate for your situation:
      </p><pre class="programlisting">
Enter keystore password:  *********
What is your first and last name?
  [Unknown]:  Matthews
What is the name of your organizational unit?
  [Unknown]:  Software Development
What is the name of your organization?
  [Unknown]:  MySQL AB
What is the name of your City or Locality?
  [Unknown]:  Flossmoor
What is the name of your State or Province?
  [Unknown]:  IL
What is the two-letter country code for this unit?
  [Unknown]:  US
Is &lt;CN=Matthews, OU=Software Development, O=MySQL AB,
 L=Flossmoor, ST=IL, C=US&gt; correct?
  [no]:  y

Enter key password for &lt;mysqlClientCertificate&gt;
        (RETURN if same as keystore password):
</pre><p>
        Finally, to get JSSE to use the keystore and truststore that you
        have generated, you need to set the following system properties
        when you start your JVM, replacing
        <em class="replaceable"><code>path_to_keystore_file</code></em> with the full
        path to the keystore file you created,
        <em class="replaceable"><code>path_to_truststore_file</code></em> with the path
        to the truststore file you created, and using the appropriate
        password values for each property. You can do this either on the
        command line:
      </p><pre class="programlisting">
-Djavax.net.ssl.keyStore=<em class="replaceable"><code>path_to_keystore_file</code></em>
-Djavax.net.ssl.keyStorePassword=<em class="replaceable"><code>password</code></em>
-Djavax.net.ssl.trustStore=<em class="replaceable"><code>path_to_truststore_file</code></em>
-Djavax.net.ssl.trustStorePassword=<em class="replaceable"><code>password</code></em>
</pre><p>
        Or you can set the values directly within the application:
      </p><pre class="programlisting">
System.setProperty("javax.net.ssl.keyStore","<em class="replaceable"><code>path_to_keystore_file</code></em>");
System.setProperty("javax.net.ssl.keyStorePassword","<em class="replaceable"><code>password</code></em>");
System.setProperty("javax.net.ssl.trustStore","<em class="replaceable"><code>path_to_truststore_file</code></em>");
System.setProperty("javax.net.ssl.trustStorePassword","<em class="replaceable"><code>password</code></em>");
</pre><p>
        You will also need to set <code class="literal">useSSL</code> to
        <code class="literal">true</code> in your connection parameters for MySQL
        Connector/J, either by adding <code class="literal">useSSL=true</code> to
        your URL, or by setting the property <code class="literal">useSSL</code>
        to <code class="literal">true</code> in the
        <code class="classname">java.util.Properties</code> instance you pass to
        <code class="literal">DriverManager.getConnection()</code>.
      </p><p>
        You can test that SSL is working by turning on JSSE debugging
        (as detailed below), and look for the following key events:
      </p><pre class="programlisting">
...
*** ClientHello, v3.1
RandomCookie:  GMT: 1018531834 bytes = { 199, 148, 180, 215, 74, 12, »
  54, 244, 0, 168, 55, 103, 215, 64, 16, 138, 225, 190, 132, 153, 2, »
  217, 219, 239, 202, 19, 121, 78 }
Session ID:  {}
Cipher Suites:  { 0, 5, 0, 4, 0, 9, 0, 10, 0, 18, 0, 19, 0, 3, 0, 17 }
Compression Methods:  { 0 }
***
[write] MD5 and SHA1 hashes:  len = 59
0000: 01 00 00 37 03 01 3D B6 90 FA C7 94 B4 D7 4A 0C  ...7..=.......J.
0010: 36 F4 00 A8 37 67 D7 40 10 8A E1 BE 84 99 02 D9  6...7g.@........
0020: DB EF CA 13 79 4E 00 00 10 00 05 00 04 00 09 00  ....yN..........
0030: 0A 00 12 00 13 00 03 00 11 01 00                 ...........
main, WRITE:  SSL v3.1 Handshake, length = 59
main, READ:  SSL v3.1 Handshake, length = 74
*** ServerHello, v3.1
RandomCookie:  GMT: 1018577560 bytes = { 116, 50, 4, 103, 25, 100, 58, »
   202, 79, 185, 178, 100, 215, 66, 254, 21, 83, 187, 190, 42, 170, 3, »
   132, 110, 82, 148, 160, 92 }
Session ID:  {163, 227, 84, 53, 81, 127, 252, 254, 178, 179, 68, 63, »
   182, 158, 30, 11, 150, 79, 170, 76, 255, 92, 15, 226, 24, 17, 177, »
   219, 158, 177, 187, 143}
Cipher Suite:  { 0, 5 }
Compression Method: 0
***
%% Created:  [Session-1, SSL_RSA_WITH_RC4_128_SHA]
** SSL_RSA_WITH_RC4_128_SHA
[read] MD5 and SHA1 hashes:  len = 74
0000: 02 00 00 46 03 01 3D B6 43 98 74 32 04 67 19 64  ...F..=.C.t2.g.d
0010: 3A CA 4F B9 B2 64 D7 42 FE 15 53 BB BE 2A AA 03  :.O..d.B..S..*..
0020: 84 6E 52 94 A0 5C 20 A3 E3 54 35 51 7F FC FE B2  .nR..\ ..T5Q....
0030: B3 44 3F B6 9E 1E 0B 96 4F AA 4C FF 5C 0F E2 18  .D?.....O.L.\...
0040: 11 B1 DB 9E B1 BB 8F 00 05 00                    ..........
main, READ:  SSL v3.1 Handshake, length = 1712
...
</pre><p>
        JSSE provides debugging (to <code class="literal">stdout</code>) when you
        set the following system property:
        <code class="literal">-Djavax.net.debug=all</code> This will tell you what
        keystores and truststores are being used, as well as what is
        going on during the SSL handshake and certificate exchange. It
        will be helpful when trying to determine what is not working
        when trying to get an SSL connection to happen.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-using-pam"></a>5.6 Connecting Using PAM Authentication</h2></div></div></div><a class="indexterm" name="idm140410758293088"></a><p>
        Java applications using Connector/J 5.1.21 and higher can
        connect to MySQL servers that use the pluggable authentication
        module (PAM) authentication scheme.
      </p><p>
        For PAM authentication to work, you must have the following:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A MySQL server that supports PAM authentication: a
            commercial distribution of MySQL 5.5.16 or higher. See
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/pam-authentication-plugin.html" target="_top">The PAM Authentication Plugin</a> for more
            information. Connector/J implements the same cleartext
            authentication method as in
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/cleartext-authentication-plugin.html" target="_top">The Cleartext Client-Side Authentication Plugin</a>.
          </p></li><li class="listitem"><p>
            SSL capability, as explained in
            <a class="xref" href="#connector-j-reference-using-ssl" title="5.5 Connecting Securely Using SSL">Section 5.5, “Connecting Securely Using SSL”</a>. Because
            the PAM authentication scheme sends the original password to
            the server, the connection to the server must be encrypted.
          </p></li></ul></div><p>
        PAM authentication support is enabled by default in Connector/J
        5.1.21 and up, so no extra configuration is needed.
      </p><p>
        To disable the PAM authentication feature, specify
        <code class="literal">mysql_clear_password</code> (the method) or
        <code class="literal">com.mysql.jdbc.authentication.MysqlClearPasswordPlugin</code>
        (the class name) in the comma-separated list of arguments for
        the <code class="literal">disabledAuthenticationPlugins</code> connection
        option. See
        <a class="xref" href="#connector-j-reference-configuration-properties" title="5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
        for Connector/J”</a>
        for details about that connection option.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-replication-connection"></a>5.7 Using Master/Slave Replication with ReplicationConnection</h2></div></div></div><p>
        See
        <a class="xref" href="#connector-j-master-slave-replication-connection" title="8.3 Configuring Master/Slave Replication with Connector/J">Section 8.3, “Configuring Master/Slave Replication with Connector/J”</a>
        for details on the topic.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-error-sqlstates"></a>5.8 Mapping MySQL Error Numbers to JDBC SQLState Codes</h2></div></div></div><a class="indexterm" name="idm140410758279696"></a><a class="indexterm" name="idm140410758278688"></a><a class="indexterm" name="idm140410758277680"></a><a class="indexterm" name="idm140410758276288"></a><a class="indexterm" name="idm140410758274896"></a><a class="indexterm" name="idm140410758273888"></a><a class="indexterm" name="idm140410758272880"></a><a class="indexterm" name="idm140410758271872"></a><a class="indexterm" name="idm140410758270864"></a><a class="indexterm" name="idm140410758269856"></a><a class="indexterm" name="idm140410758268848"></a><a class="indexterm" name="idm140410758267840"></a><a class="indexterm" name="idm140410758266832"></a><a class="indexterm" name="idm140410758265824"></a><a class="indexterm" name="idm140410758264816"></a><a class="indexterm" name="idm140410758263808"></a><a class="indexterm" name="idm140410758262800"></a><a class="indexterm" name="idm140410758261792"></a><a class="indexterm" name="idm140410758260784"></a><a class="indexterm" name="idm140410758259776"></a><a class="indexterm" name="idm140410758258768"></a><a class="indexterm" name="idm140410758257760"></a><a class="indexterm" name="idm140410758256752"></a><a class="indexterm" name="idm140410758255744"></a><a class="indexterm" name="idm140410758254736"></a><a class="indexterm" name="idm140410758253728"></a><a class="indexterm" name="idm140410758252720"></a><a class="indexterm" name="idm140410758251712"></a><a class="indexterm" name="idm140410758250704"></a><a class="indexterm" name="idm140410758249696"></a><a class="indexterm" name="idm140410758248688"></a><a class="indexterm" name="idm140410758247680"></a><a class="indexterm" name="idm140410758246672"></a><a class="indexterm" name="idm140410758245664"></a><a class="indexterm" name="idm140410758244656"></a><a class="indexterm" name="idm140410758243648"></a><a class="indexterm" name="idm140410758242640"></a><a class="indexterm" name="idm140410758241632"></a><a class="indexterm" name="idm140410758240624"></a><a class="indexterm" name="idm140410758239616"></a><a class="indexterm" name="idm140410758238608"></a><a class="indexterm" name="idm140410758237600"></a><a class="indexterm" name="idm140410758236592"></a><a class="indexterm" name="idm140410758235584"></a><a class="indexterm" name="idm140410758234576"></a><a class="indexterm" name="idm140410758233568"></a><a class="indexterm" name="idm140410758232560"></a><a class="indexterm" name="idm140410758231552"></a><a class="indexterm" name="idm140410758230544"></a><a class="indexterm" name="idm140410758229536"></a><a class="indexterm" name="idm140410758228528"></a><a class="indexterm" name="idm140410758227520"></a><a class="indexterm" name="idm140410758226512"></a><a class="indexterm" name="idm140410758225504"></a><a class="indexterm" name="idm140410758224496"></a><a class="indexterm" name="idm140410758223488"></a><a class="indexterm" name="idm140410758222480"></a><a class="indexterm" name="idm140410758221472"></a><a class="indexterm" name="idm140410758220464"></a><a class="indexterm" name="idm140410758219456"></a><a class="indexterm" name="idm140410758218448"></a><a class="indexterm" name="idm140410758217440"></a><a class="indexterm" name="idm140410758216432"></a><a class="indexterm" name="idm140410758215424"></a><a class="indexterm" name="idm140410758214416"></a><a class="indexterm" name="idm140410758213408"></a><a class="indexterm" name="idm140410758212400"></a><a class="indexterm" name="idm140410758211392"></a><a class="indexterm" name="idm140410758210384"></a><a class="indexterm" name="idm140410758209376"></a><a class="indexterm" name="idm140410758208368"></a><a class="indexterm" name="idm140410758207360"></a><a class="indexterm" name="idm140410758206352"></a><a class="indexterm" name="idm140410758205344"></a><a class="indexterm" name="idm140410758204336"></a><a class="indexterm" name="idm140410758203328"></a><a class="indexterm" name="idm140410758202320"></a><a class="indexterm" name="idm140410758201312"></a><a class="indexterm" name="idm140410758200304"></a><a class="indexterm" name="idm140410758199296"></a><a class="indexterm" name="idm140410758198288"></a><a class="indexterm" name="idm140410758197280"></a><a class="indexterm" name="idm140410758196272"></a><a class="indexterm" name="idm140410758195264"></a><a class="indexterm" name="idm140410758194256"></a><a class="indexterm" name="idm140410758193248"></a><a class="indexterm" name="idm140410758192240"></a><a class="indexterm" name="idm140410758191232"></a><a class="indexterm" name="idm140410758190224"></a><a class="indexterm" name="idm140410758189216"></a><a class="indexterm" name="idm140410758188208"></a><a class="indexterm" name="idm140410758187200"></a><a class="indexterm" name="idm140410758186192"></a><a class="indexterm" name="idm140410758185184"></a><a class="indexterm" name="idm140410758184176"></a><a class="indexterm" name="idm140410758183168"></a><a class="indexterm" name="idm140410758182160"></a><a class="indexterm" name="idm140410758181152"></a><a class="indexterm" name="idm140410758180144"></a><a class="indexterm" name="idm140410758179136"></a><a class="indexterm" name="idm140410758178128"></a><a class="indexterm" name="idm140410758177120"></a><a class="indexterm" name="idm140410758176112"></a><a class="indexterm" name="idm140410758175104"></a><a class="indexterm" name="idm140410758174096"></a><a class="indexterm" name="idm140410758173088"></a><a class="indexterm" name="idm140410758172080"></a><a class="indexterm" name="idm140410758171072"></a><a class="indexterm" name="idm140410758170064"></a><a class="indexterm" name="idm140410758169056"></a><a class="indexterm" name="idm140410758168048"></a><a class="indexterm" name="idm140410758167040"></a><a class="indexterm" name="idm140410758166032"></a><a class="indexterm" name="idm140410758165024"></a><a class="indexterm" name="idm140410758164016"></a><a class="indexterm" name="idm140410758163008"></a><a class="indexterm" name="idm140410758162000"></a><a class="indexterm" name="idm140410758160992"></a><a class="indexterm" name="idm140410758159984"></a><a class="indexterm" name="idm140410758158976"></a><a class="indexterm" name="idm140410758157968"></a><a class="indexterm" name="idm140410758156960"></a><a class="indexterm" name="idm140410758155952"></a><a class="indexterm" name="idm140410758154944"></a><a class="indexterm" name="idm140410758153936"></a><a class="indexterm" name="idm140410758152928"></a><a class="indexterm" name="idm140410758151920"></a><a class="indexterm" name="idm140410758150912"></a><a class="indexterm" name="idm140410758149904"></a><a class="indexterm" name="idm140410758148896"></a><a class="indexterm" name="idm140410758147888"></a><a class="indexterm" name="idm140410758146880"></a><a class="indexterm" name="idm140410758145872"></a><a class="indexterm" name="idm140410758144864"></a><a class="indexterm" name="idm140410758143856"></a><a class="indexterm" name="idm140410758142848"></a><a class="indexterm" name="idm140410758141840"></a><p>
        The table below provides a mapping of the MySQL error numbers to
        JDBC <code class="literal">SQLState</code> values.
      </p><div class="table"><a name="idm140410758139728"></a><p class="title"><b>Table 5.4 Mapping of MySQL Error Numbers to SQLStates</b></p><div class="table-contents"><table summary="Mapping of MySQL Error Numbers to SQLStates" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th scope="col">MySQL Error Number</th><th scope="col">MySQL Error Name</th><th scope="col">Legacy (X/Open) SQLState</th><th scope="col">SQL Standard SQLState</th></tr></thead><tbody><tr><td scope="row">1022</td><td>ER_DUP_KEY</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1037</td><td>ER_OUTOFMEMORY</td><td>S1001</td><td>HY001</td></tr><tr><td scope="row">1038</td><td>ER_OUT_OF_SORTMEMORY</td><td>S1001</td><td>HY001</td></tr><tr><td scope="row">1040</td><td>ER_CON_COUNT_ERROR</td><td>08004</td><td>08004</td></tr><tr><td scope="row">1042</td><td>ER_BAD_HOST_ERROR</td><td>08004</td><td>08S01</td></tr><tr><td scope="row">1043</td><td>ER_HANDSHAKE_ERROR</td><td>08004</td><td>08S01</td></tr><tr><td scope="row">1044</td><td>ER_DBACCESS_DENIED_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1045</td><td>ER_ACCESS_DENIED_ERROR</td><td>28000</td><td>28000</td></tr><tr><td scope="row">1046</td><td>ER_NO_DB_ERROR</td><td>3D000</td><td>3D000</td></tr><tr><td scope="row">1047</td><td>ER_UNKNOWN_COM_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1048</td><td>ER_BAD_NULL_ERROR</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1049</td><td>ER_BAD_DB_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1050</td><td>ER_TABLE_EXISTS_ERROR</td><td>42S01</td><td>42S01</td></tr><tr><td scope="row">1051</td><td>ER_BAD_TABLE_ERROR</td><td>42S02</td><td>42S02</td></tr><tr><td scope="row">1052</td><td>ER_NON_UNIQ_ERROR</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1053</td><td>ER_SERVER_SHUTDOWN</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1054</td><td>ER_BAD_FIELD_ERROR</td><td>S0022</td><td>42S22</td></tr><tr><td scope="row">1055</td><td>ER_WRONG_FIELD_WITH_GROUP</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1056</td><td>ER_WRONG_GROUP_FIELD</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1057</td><td>ER_WRONG_SUM_SELECT</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1058</td><td>ER_WRONG_VALUE_COUNT</td><td>21S01</td><td>21S01</td></tr><tr><td scope="row">1059</td><td>ER_TOO_LONG_IDENT</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1060</td><td>ER_DUP_FIELDNAME</td><td>S1009</td><td>42S21</td></tr><tr><td scope="row">1061</td><td>ER_DUP_KEYNAME</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1062</td><td>ER_DUP_ENTRY</td><td>S1009</td><td>23000</td></tr><tr><td scope="row">1063</td><td>ER_WRONG_FIELD_SPEC</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1064</td><td>ER_PARSE_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1065</td><td>ER_EMPTY_QUERY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1066</td><td>ER_NONUNIQ_TABLE</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1067</td><td>ER_INVALID_DEFAULT</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1068</td><td>ER_MULTIPLE_PRI_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1069</td><td>ER_TOO_MANY_KEYS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1070</td><td>ER_TOO_MANY_KEY_PARTS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1071</td><td>ER_TOO_LONG_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1072</td><td>ER_KEY_COLUMN_DOES_NOT_EXITS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1073</td><td>ER_BLOB_USED_AS_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1074</td><td>ER_TOO_BIG_FIELDLENGTH</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1075</td><td>ER_WRONG_AUTO_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1080</td><td>ER_FORCING_CLOSE</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1081</td><td>ER_IPSOCK_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1082</td><td>ER_NO_SUCH_INDEX</td><td>S1009</td><td>42S12</td></tr><tr><td scope="row">1083</td><td>ER_WRONG_FIELD_TERMINATORS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1084</td><td>ER_BLOBS_AND_NO_TERMINATED</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1090</td><td>ER_CANT_REMOVE_ALL_FIELDS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1091</td><td>ER_CANT_DROP_FIELD_OR_KEY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1101</td><td>ER_BLOB_CANT_HAVE_DEFAULT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1102</td><td>ER_WRONG_DB_NAME</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1103</td><td>ER_WRONG_TABLE_NAME</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1104</td><td>ER_TOO_BIG_SELECT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1106</td><td>ER_UNKNOWN_PROCEDURE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1107</td><td>ER_WRONG_PARAMCOUNT_TO_PROCEDURE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1109</td><td>ER_UNKNOWN_TABLE</td><td>42S02</td><td>42S02</td></tr><tr><td scope="row">1110</td><td>ER_FIELD_SPECIFIED_TWICE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1112</td><td>ER_UNSUPPORTED_EXTENSION</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1113</td><td>ER_TABLE_MUST_HAVE_COLUMNS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1115</td><td>ER_UNKNOWN_CHARACTER_SET</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1118</td><td>ER_TOO_BIG_ROWSIZE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1120</td><td>ER_WRONG_OUTER_JOIN</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1121</td><td>ER_NULL_COLUMN_IN_INDEX</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1129</td><td>ER_HOST_IS_BLOCKED</td><td>08004</td><td>HY000</td></tr><tr><td scope="row">1130</td><td>ER_HOST_NOT_PRIVILEGED</td><td>08004</td><td>HY000</td></tr><tr><td scope="row">1131</td><td>ER_PASSWORD_ANONYMOUS_USER</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1132</td><td>ER_PASSWORD_NOT_ALLOWED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1133</td><td>ER_PASSWORD_NO_MATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1136</td><td>ER_WRONG_VALUE_COUNT_ON_ROW</td><td>21S01</td><td>21S01</td></tr><tr><td scope="row">1138</td><td>ER_INVALID_USE_OF_NULL</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1139</td><td>ER_REGEXP_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1140</td><td>ER_MIX_OF_GROUP_FUNC_AND_FIELDS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1141</td><td>ER_NONEXISTING_GRANT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1142</td><td>ER_TABLEACCESS_DENIED_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1143</td><td>ER_COLUMNACCESS_DENIED_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1144</td><td>ER_ILLEGAL_GRANT_FOR_TABLE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1145</td><td>ER_GRANT_WRONG_HOST_OR_USER</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1146</td><td>ER_NO_SUCH_TABLE</td><td>42S02</td><td>42S02</td></tr><tr><td scope="row">1147</td><td>ER_NONEXISTING_TABLE_GRANT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1148</td><td>ER_NOT_ALLOWED_COMMAND</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1149</td><td>ER_SYNTAX_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1152</td><td>ER_ABORTING_CONNECTION</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1153</td><td>ER_NET_PACKET_TOO_LARGE</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1154</td><td>ER_NET_READ_ERROR_FROM_PIPE</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1155</td><td>ER_NET_FCNTL_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1156</td><td>ER_NET_PACKETS_OUT_OF_ORDER</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1157</td><td>ER_NET_UNCOMPRESS_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1158</td><td>ER_NET_READ_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1159</td><td>ER_NET_READ_INTERRUPTED</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1160</td><td>ER_NET_ERROR_ON_WRITE</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1161</td><td>ER_NET_WRITE_INTERRUPTED</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1162</td><td>ER_TOO_LONG_STRING</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1163</td><td>ER_TABLE_CANT_HANDLE_BLOB</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1164</td><td>ER_TABLE_CANT_HANDLE_AUTO_INCREMENT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1166</td><td>ER_WRONG_COLUMN_NAME</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1167</td><td>ER_WRONG_KEY_COLUMN</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1169</td><td>ER_DUP_UNIQUE</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1170</td><td>ER_BLOB_KEY_WITHOUT_LENGTH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1171</td><td>ER_PRIMARY_CANT_HAVE_NULL</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1172</td><td>ER_TOO_MANY_ROWS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1173</td><td>ER_REQUIRES_PRIMARY_KEY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1176</td><td>ER_KEY_DOES_NOT_EXITS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1177</td><td>ER_CHECK_NO_SUCH_TABLE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1178</td><td>ER_CHECK_NOT_IMPLEMENTED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1179</td><td>ER_CANT_DO_THIS_DURING_AN_TRANSACTION</td><td>25000</td><td>25000</td></tr><tr><td scope="row">1184</td><td>ER_NEW_ABORTING_CONNECTION</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1189</td><td>ER_MASTER_NET_READ</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1190</td><td>ER_MASTER_NET_WRITE</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1203</td><td>ER_TOO_MANY_USER_CONNECTIONS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1205</td><td>ER_LOCK_WAIT_TIMEOUT</td><td>40001</td><td>40001</td></tr><tr><td scope="row">1207</td><td>ER_READ_ONLY_TRANSACTION</td><td>25000</td><td>25000</td></tr><tr><td scope="row">1211</td><td>ER_NO_PERMISSION_TO_CREATE_USER</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1213</td><td>ER_LOCK_DEADLOCK</td><td>40001</td><td>40001</td></tr><tr><td scope="row">1216</td><td>ER_NO_REFERENCED_ROW</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1217</td><td>ER_ROW_IS_REFERENCED</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1218</td><td>ER_CONNECT_TO_MASTER</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1222</td><td>ER_WRONG_NUMBER_OF_COLUMNS_IN_SELECT</td><td>21000</td><td>21000</td></tr><tr><td scope="row">1226</td><td>ER_USER_LIMIT_REACHED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1227</td><td>ER_SPECIFIC_ACCESS_DENIED_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1230</td><td>ER_NO_DEFAULT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1231</td><td>ER_WRONG_VALUE_FOR_VAR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1232</td><td>ER_WRONG_TYPE_FOR_VAR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1234</td><td>ER_CANT_USE_OPTION_HERE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1235</td><td>ER_NOT_SUPPORTED_YET</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1239</td><td>ER_WRONG_FK_DEF</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1241</td><td>ER_OPERAND_COLUMNS</td><td>21000</td><td>21000</td></tr><tr><td scope="row">1242</td><td>ER_SUBQUERY_NO_1_ROW</td><td>21000</td><td>21000</td></tr><tr><td scope="row">1247</td><td>ER_ILLEGAL_REFERENCE</td><td>42S22</td><td>42S22</td></tr><tr><td scope="row">1248</td><td>ER_DERIVED_MUST_HAVE_ALIAS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1249</td><td>ER_SELECT_REDUCED</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1250</td><td>ER_TABLENAME_NOT_ALLOWED_HERE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1251</td><td>ER_NOT_SUPPORTED_AUTH_MODE</td><td>08004</td><td>08004</td></tr><tr><td scope="row">1252</td><td>ER_SPATIAL_CANT_HAVE_NULL</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1253</td><td>ER_COLLATION_CHARSET_MISMATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1261</td><td>ER_WARN_TOO_FEW_RECORDS</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1262</td><td>ER_WARN_TOO_MANY_RECORDS</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1263</td><td>ER_WARN_NULL_TO_NOTNULL</td><td>S1000</td><td>01000</td></tr><tr><td scope="row">1264</td><td>ER_WARN_DATA_OUT_OF_RANGE</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1265</td><td>ER_WARN_DATA_TRUNCATED</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1280</td><td>ER_WRONG_NAME_FOR_INDEX</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1281</td><td>ER_WRONG_NAME_FOR_CATALOG</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1286</td><td>ER_UNKNOWN_STORAGE_ENGINE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1292</td><td>ER_TRUNCATED_WRONG_VALUE</td><td>22007</td><td>22007</td></tr><tr><td scope="row">1303</td><td>ER_SP_NO_RECURSIVE_CREATE</td><td>S1000</td><td>2F003</td></tr><tr><td scope="row">1304</td><td>ER_SP_ALREADY_EXISTS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1305</td><td>ER_SP_DOES_NOT_EXIST</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1308</td><td>ER_SP_LILABEL_MISMATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1309</td><td>ER_SP_LABEL_REDEFINE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1310</td><td>ER_SP_LABEL_MISMATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1311</td><td>ER_SP_UNINIT_VAR</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1312</td><td>ER_SP_BADSELECT</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1313</td><td>ER_SP_BADRETURN</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1314</td><td>ER_SP_BADSTATEMENT</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1315</td><td>ER_UPDATE_LOG_DEPRECATED_IGNORED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1316</td><td>ER_UPDATE_LOG_DEPRECATED_TRANSLATED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1317</td><td>ER_QUERY_INTERRUPTED</td><td>S1000</td><td>70100</td></tr><tr><td scope="row">1318</td><td>ER_SP_WRONG_NO_OF_ARGS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1319</td><td>ER_SP_COND_MISMATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1320</td><td>ER_SP_NORETURN</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1321</td><td>ER_SP_NORETURNEND</td><td>S1000</td><td>2F005</td></tr><tr><td scope="row">1322</td><td>ER_SP_BAD_CURSOR_QUERY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1323</td><td>ER_SP_BAD_CURSOR_SELECT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1324</td><td>ER_SP_CURSOR_MISMATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1325</td><td>ER_SP_CURSOR_ALREADY_OPEN</td><td>24000</td><td>24000</td></tr><tr><td scope="row">1326</td><td>ER_SP_CURSOR_NOT_OPEN</td><td>24000</td><td>24000</td></tr><tr><td scope="row">1327</td><td>ER_SP_UNDECLARED_VAR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1329</td><td>ER_SP_FETCH_NO_DATA</td><td>S1000</td><td>02000</td></tr><tr><td scope="row">1330</td><td>ER_SP_DUP_PARAM</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1331</td><td>ER_SP_DUP_VAR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1332</td><td>ER_SP_DUP_COND</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1333</td><td>ER_SP_DUP_CURS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1335</td><td>ER_SP_SUBSELECT_NYI</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1336</td><td>ER_STMT_NOT_ALLOWED_IN_SF_OR_TRG</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1337</td><td>ER_SP_VARCOND_AFTER_CURSHNDLR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1338</td><td>ER_SP_CURSOR_AFTER_HANDLER</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1339</td><td>ER_SP_CASE_NOT_FOUND</td><td>S1000</td><td>20000</td></tr><tr><td scope="row">1365</td><td>ER_DIVISION_BY_ZERO</td><td>22012</td><td>22012</td></tr><tr><td scope="row">1367</td><td>ER_ILLEGAL_VALUE_FOR_TYPE</td><td>22007</td><td>22007</td></tr><tr><td scope="row">1370</td><td>ER_PROCACCESS_DENIED_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1397</td><td>ER_XAER_NOTA</td><td>S1000</td><td>XAE04</td></tr><tr><td scope="row">1398</td><td>ER_XAER_INVAL</td><td>S1000</td><td>XAE05</td></tr><tr><td scope="row">1399</td><td>ER_XAER_RMFAIL</td><td>S1000</td><td>XAE07</td></tr><tr><td scope="row">1400</td><td>ER_XAER_OUTSIDE</td><td>S1000</td><td>XAE09</td></tr><tr><td scope="row">1401</td><td>ER_XA_RMERR</td><td>S1000</td><td>XAE03</td></tr><tr><td scope="row">1402</td><td>ER_XA_RBROLLBACK</td><td>S1000</td><td>XA100</td></tr><tr><td scope="row">1403</td><td>ER_NONEXISTING_PROC_GRANT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1406</td><td>ER_DATA_TOO_LONG</td><td>22001</td><td>22001</td></tr><tr><td scope="row">1407</td><td>ER_SP_BAD_SQLSTATE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1410</td><td>ER_CANT_CREATE_USER_WITH_GRANT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1413</td><td>ER_SP_DUP_HANDLER</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1414</td><td>ER_SP_NOT_VAR_ARG</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1415</td><td>ER_SP_NO_RETSET</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1416</td><td>ER_CANT_CREATE_GEOMETRY_OBJECT</td><td>22003</td><td>22003</td></tr><tr><td scope="row">1425</td><td>ER_TOO_BIG_SCALE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1426</td><td>ER_TOO_BIG_PRECISION</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1427</td><td>ER_M_BIGGER_THAN_D</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1437</td><td>ER_TOO_LONG_BODY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1439</td><td>ER_TOO_BIG_DISPLAYWIDTH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1440</td><td>ER_XAER_DUPID</td><td>S1000</td><td>XAE08</td></tr><tr><td scope="row">1441</td><td>ER_DATETIME_FUNCTION_OVERFLOW</td><td>22008</td><td>22008</td></tr><tr><td scope="row">1451</td><td>ER_ROW_IS_REFERENCED_2</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1452</td><td>ER_NO_REFERENCED_ROW_2</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1453</td><td>ER_SP_BAD_VAR_SHADOW</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1458</td><td>ER_SP_WRONG_NAME</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1460</td><td>ER_SP_NO_AGGREGATE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1461</td><td>ER_MAX_PREPARED_STMT_COUNT_REACHED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1463</td><td>ER_NON_GROUPING_FIELD_USED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1557</td><td>ER_FOREIGN_DUPLICATE_KEY</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1568</td><td>ER_CANT_CHANGE_TX_ISOLATION</td><td>S1000</td><td>25001</td></tr><tr><td scope="row">1582</td><td>ER_WRONG_PARAMCOUNT_TO_NATIVE_FCT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1583</td><td>ER_WRONG_PARAMETERS_TO_NATIVE_FCT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1584</td><td>ER_WRONG_PARAMETERS_TO_STORED_FCT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1586</td><td>ER_DUP_ENTRY_WITH_KEY_NAME</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1613</td><td>ER_XA_RBTIMEOUT</td><td>S1000</td><td>XA106</td></tr><tr><td scope="row">1614</td><td>ER_XA_RBDEADLOCK</td><td>S1000</td><td>XA102</td></tr><tr><td scope="row">1630</td><td>ER_FUNC_INEXISTENT_NAME_COLLISION</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1641</td><td>ER_DUP_SIGNAL_SET</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1642</td><td>ER_SIGNAL_WARN</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1643</td><td>ER_SIGNAL_NOT_FOUND</td><td>S1000</td><td>02000</td></tr><tr><td scope="row">1645</td><td>ER_RESIGNAL_WITHOUT_ACTIVE_HANDLER</td><td>S1000</td><td>0K000</td></tr><tr><td scope="row">1687</td><td>ER_SPATIAL_MUST_HAVE_GEOM_COL</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1690</td><td>ER_DATA_OUT_OF_RANGE</td><td>22003</td><td>22003</td></tr><tr><td scope="row">1698</td><td>ER_ACCESS_DENIED_NO_PASSWORD_ERROR</td><td>28000</td><td>28000</td></tr><tr><td scope="row">1701</td><td>ER_TRUNCATE_ILLEGAL_FK</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1758</td><td>ER_DA_INVALID_CONDITION_NUMBER</td><td>35000</td><td>35000</td></tr><tr><td scope="row">1761</td><td>ER_FOREIGN_DUPLICATE_KEY_WITH_CHILD_INFO</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1762</td><td>ER_FOREIGN_DUPLICATE_KEY_WITHOUT_CHILD_INFO</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1792</td><td>ER_CANT_EXECUTE_IN_READ_ONLY_TRANSACTION</td><td>S1000</td><td>25006</td></tr><tr><td scope="row">1845</td><td>ER_ALTER_OPERATION_NOT_SUPPORTED</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1846</td><td>ER_ALTER_OPERATION_NOT_SUPPORTED_REASON</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1859</td><td>ER_DUP_UNKNOWN_IN_INDEX</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1873</td><td>ER_ACCESS_DENIED_CHANGE_USER_ERROR</td><td>28000</td><td>28000</td></tr><tr><td scope="row">1887</td><td>ER_GET_STACKED_DA_WITHOUT_ACTIVE_HANDLER</td><td>S1000</td><td>0Z002</td></tr><tr><td scope="row">1903</td><td>ER_INVALID_ARGUMENT_FOR_LOGARITHM</td><td>S1000</td><td>2201E</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-basic"></a>Chapter 6 JDBC Concepts</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-usagenotes-connect-drivermanager">6.1 Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
        Interface</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements">6.2 Using JDBC <code class="literal">Statement</code> Objects to Execute SQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements-callable">6.3 Using JDBC <code class="literal">CallableStatements</code> to Execute Stored
        Procedures</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-last-insert-id">6.4 Retrieving <code class="literal">AUTO_INCREMENT</code> Column Values through JDBC</a></span></dt></dl></div><a class="indexterm" name="idm140410757690928"></a><p>
      This section provides some general JDBC background.
    </p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-connect-drivermanager"></a>6.1 Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
        Interface</h2></div></div></div><p>
        When you are using JDBC outside of an application server, the
        <code class="literal">DriverManager</code> class manages the establishment
        of connections.
      </p><p>
        Specify to the <code class="literal">DriverManager</code> which JDBC
        drivers to try to make Connections with. The easiest way to do
        this is to use <code class="literal">Class.forName()</code> on the class
        that implements the <code class="literal">java.sql.Driver</code>
        interface. With MySQL Connector/J, the name of this class is
        <code class="literal">com.mysql.jdbc.Driver</code>. With this method, you
        could use an external configuration file to supply the driver
        class name and driver parameters to use when connecting to a
        database.
      </p><p>
        The following section of Java code shows how you might register
        MySQL Connector/J from the <code class="function">main()</code> method of
        your application. If testing this code, first read the
        installation section at
        <a class="xref" href="#connector-j-installing" title="Chapter 3 Connector/J Installation">Chapter 3, <i>Connector/J Installation</i></a>, to make sure you have
        connector installed correctly and the
        <code class="literal">CLASSPATH</code> set up. Also, ensure that MySQL is
        configured to accept external TCP/IP connections.
      </p><pre class="programlisting">
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

// Notice, do not import com.mysql.jdbc.*
// or you will have problems!

public class LoadDriver {
    public static void main(String[] args) {
        try {
            // The newInstance() call is a work around for some
            // broken Java implementations

            Class.forName("com.mysql.jdbc.Driver").newInstance();
        } catch (Exception ex) {
            // handle the error
        }
    }
}
</pre><p>
        After the driver has been registered with the
        <code class="literal">DriverManager</code>, you can obtain a
        <code class="literal">Connection</code> instance that is connected to a
        particular database by calling
        <code class="literal">DriverManager.getConnection()</code>:
      </p><div class="example"><a name="connector-j-examples-connection-drivermanager"></a><p class="title"><b>Example 6.1 Connector/J: Obtaining a connection from the
          <code class="literal">DriverManager</code></b></p><div class="example-contents"><p>
          If you have not already done so, please review the portion of
          <a class="xref" href="#connector-j-usagenotes-connect-drivermanager" title="6.1 Connecting to MySQL Using the JDBC DriverManager Interface">Section 6.1, “Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
        Interface”</a>
          above before working with the example below.
        </p><p>
          This example shows how you can obtain a
          <code class="literal">Connection</code> instance from the
          <code class="literal">DriverManager</code>. There are a few different
          signatures for the <code class="function">getConnection()</code>
          method. Consult the API documentation that comes with your JDK
          for more specific information on how to use them.
        </p><pre class="programlisting">
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

Connection conn = null;
...
try {
    conn =
       DriverManager.getConnection("jdbc:mysql://localhost/test?" +
                                   "user=minty&amp;password=greatsqldb");

    // Do something with the Connection

   ...
} catch (SQLException ex) {
    // handle any errors
    System.out.println("SQLException: " + ex.getMessage());
    System.out.println("SQLState: " + ex.getSQLState());
    System.out.println("VendorError: " + ex.getErrorCode());
}
</pre><p>
          Once a <code class="classname">Connection</code> is established, it
          can be used to create <code class="classname">Statement</code> and
          <code class="classname">PreparedStatement</code> objects, as well as
          retrieve metadata about the database. This is explained in the
          following sections.
        </p></div></div><br class="example-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-statements"></a>6.2 Using JDBC <code class="literal">Statement</code> Objects to Execute SQL</h2></div></div></div><p>
        <code class="classname">Statement</code> objects allow you to execute
        basic SQL queries and retrieve the results through the
        <code class="literal">ResultSet</code> class, which is described later.
      </p><p>
        To create a <code class="classname">Statement</code> instance, you call
        the <code class="function">createStatement()</code> method on the
        <code class="literal">Connection</code> object you have retrieved using
        one of the <code class="literal">DriverManager.getConnection()</code> or
        <code class="literal">DataSource.getConnection()</code> methods described
        earlier.
      </p><p>
        Once you have a <code class="classname">Statement</code> instance, you
        can execute a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> query by
        calling the <code class="function">executeQuery(String)</code> method
        with the SQL you want to use.
      </p><p>
        To update data in the database, use the
        <code class="function">executeUpdate(String SQL)</code> method. This
        method returns the number of rows matched by the update
        statement, not the number of rows that were modified.
      </p><p>
        If you do not know ahead of time whether the SQL statement will
        be a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> or an
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/update.html" target="_top"><code class="literal">UPDATE</code></a>/<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/insert.html" target="_top"><code class="literal">INSERT</code></a>,
        then you can use the <code class="function">execute(String SQL)</code>
        method. This method will return true if the SQL query was a
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a>, or false if it was an
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/update.html" target="_top"><code class="literal">UPDATE</code></a>,
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/insert.html" target="_top"><code class="literal">INSERT</code></a>, or
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/delete.html" target="_top"><code class="literal">DELETE</code></a> statement. If the
        statement was a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> query, you
        can retrieve the results by calling the
        <code class="function">getResultSet()</code> method. If the statement was
        an <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/update.html" target="_top"><code class="literal">UPDATE</code></a>,
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/insert.html" target="_top"><code class="literal">INSERT</code></a>, or
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/delete.html" target="_top"><code class="literal">DELETE</code></a> statement, you can
        retrieve the affected rows count by calling
        <code class="function">getUpdateCount()</code> on the
        <code class="classname">Statement</code> instance.
      </p><div class="example"><a name="connector-j-examples-execute-select"></a><p class="title"><b>Example 6.2 Connector/J: Using java.sql.Statement to execute a
          <code class="literal">SELECT</code> query</b></p><div class="example-contents"><pre class="programlisting">
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;
import java.sql.ResultSet;

// assume that conn is an already created JDBC connection (see previous examples)

Statement stmt = null;
ResultSet rs = null;

try {
    stmt = conn.createStatement();
    rs = stmt.executeQuery("SELECT foo FROM bar");

    // or alternatively, if you don't know ahead of time that
    // the query will be a SELECT...

    if (stmt.execute("SELECT foo FROM bar")) {
        rs = stmt.getResultSet();
    }

    // Now do something with the ResultSet ....
}
catch (SQLException ex){
    // handle any errors
    System.out.println("SQLException: " + ex.getMessage());
    System.out.println("SQLState: " + ex.getSQLState());
    System.out.println("VendorError: " + ex.getErrorCode());
}
finally {
    // it is a good idea to release
    // resources in a finally{} block
    // in reverse-order of their creation
    // if they are no-longer needed

    if (rs != null) {
        try {
            rs.close();
        } catch (SQLException sqlEx) { } // ignore

        rs = null;
    }

    if (stmt != null) {
        try {
            stmt.close();
        } catch (SQLException sqlEx) { } // ignore

        stmt = null;
    }
}
</pre></div></div><br class="example-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-statements-callable"></a>6.3 Using JDBC <code class="literal">CallableStatements</code> to Execute Stored
        Procedures</h2></div></div></div><p>
        Starting with MySQL server version 5.0 when used with
        Connector/J 3.1.1 or newer, the
        <code class="classname">java.sql.CallableStatement</code> interface is
        fully implemented with the exception of the
        <code class="function">getParameterMetaData()</code> method.
      </p><p>
        For more information on MySQL stored procedures, please refer to
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/stored-routines.html" target="_top">Using Stored Routines (Procedures and Functions)</a>.
      </p><p>
        Connector/J exposes stored procedure functionality through
        JDBC's <code class="classname">CallableStatement</code> interface.
      </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
          Current versions of MySQL server do not return enough
          information for the JDBC driver to provide result set metadata
          for callable statements. This means that when using
          <code class="literal">CallableStatement</code>,
          <code class="literal">ResultSetMetaData</code> may return
          <code class="literal">NULL</code>.
        </p></div><p>
        The following example shows a stored procedure that returns the
        value of <code class="varname">inOutParam</code> incremented by 1, and the
        string passed in using <code class="varname">inputParam</code> as a
        <code class="classname">ResultSet</code>:

        </p><div class="example"><a name="connector-j-examples-stored-procedure"></a><p class="title"><b>Example 6.3 Connector/J: Calling Stored Procedures</b></p><div class="example-contents"><pre class="programlisting">
CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), \
                        INOUT inOutParam INT)
BEGIN
    DECLARE z INT;
    SET z = inOutParam + 1;
    SET inOutParam = z;

    SELECT inputParam;

    SELECT CONCAT('zyxw', inputParam);
END
</pre></div></div><p><br class="example-break">
      </p><p>
        To use the <code class="literal">demoSp</code> procedure with Connector/J,
        follow these steps:
      </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
            Prepare the callable statement by using
            <code class="literal">Connection.prepareCall()</code>.
          </p><p>
            Notice that you have to use JDBC escape syntax, and that the
            parentheses surrounding the parameter placeholders are not
            optional:
          </p><div class="example"><a name="connector-j-examples-preparecall"></a><p class="title"><b>Example 6.4 Connector/J: Using <code class="literal">Connection.prepareCall()</code></b></p><div class="example-contents"><pre class="programlisting">
import java.sql.CallableStatement;

...

    //
    // Prepare a call to the stored procedure 'demoSp'
    // with two parameters
    //
    // Notice the use of JDBC-escape syntax ({call ...})
    //

    CallableStatement cStmt = conn.prepareCall("{call demoSp(?, ?)}");



    cStmt.setString(1, "abcdefg");
</pre></div></div><br class="example-break"><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
              <code class="literal">Connection.prepareCall()</code> is an
              expensive method, due to the metadata retrieval that the
              driver performs to support output parameters. For
              performance reasons, minimize unnecessary calls to
              <code class="literal">Connection.prepareCall()</code> by reusing
              <code class="classname">CallableStatement</code> instances in your
              code.
            </p></div></li><li class="listitem"><p>
            Register the output parameters (if any exist)
          </p><p>
            To retrieve the values of output parameters (parameters
            specified as <code class="literal">OUT</code> or
            <code class="literal">INOUT</code> when you created the stored
            procedure), JDBC requires that they be specified before
            statement execution using the various
            <code class="function">registerOutputParameter()</code> methods in
            the <code class="classname">CallableStatement</code> interface:

            </p><div class="example"><a name="connector-j-examples-output-param"></a><p class="title"><b>Example 6.5 Connector/J: Registering output parameters</b></p><div class="example-contents"><pre class="programlisting">
import java.sql.Types;
...
//
// Connector/J supports both named and indexed
// output parameters. You can register output
// parameters using either method, as well
// as retrieve output parameters using either
// method, regardless of what method was
// used to register them.
//
// The following examples show how to use
// the various methods of registering
// output parameters (you should of course
// use only one registration per parameter).
//

//
// Registers the second parameter as output, and
// uses the type 'INTEGER' for values returned from
// getObject()
//

cStmt.registerOutParameter(2, Types.INTEGER);

//
// Registers the named parameter 'inOutParam', and
// uses the type 'INTEGER' for values returned from
// getObject()
//

cStmt.registerOutParameter("inOutParam", Types.INTEGER);
...
</pre></div></div><p><br class="example-break">
          </p></li><li class="listitem"><p>
            Set the input parameters (if any exist)
          </p><p>
            Input and in/out parameters are set as for
            <code class="classname">PreparedStatement</code> objects. However,
            <code class="classname">CallableStatement</code> also supports
            setting parameters by name:

            </p><div class="example"><a name="connector-j-examples-callablestatement"></a><p class="title"><b>Example 6.6 Connector/J: Setting <code class="literal">CallableStatement</code> input
                parameters</b></p><div class="example-contents"><pre class="programlisting">
...

    //
    // Set a parameter by index
    //

    cStmt.setString(1, "abcdefg");

    //
    // Alternatively, set a parameter using
    // the parameter name
    //

    cStmt.setString("inputParameter", "abcdefg");

    //
    // Set the 'in/out' parameter using an index
    //

    cStmt.setInt(2, 1);

    //
    // Alternatively, set the 'in/out' parameter
    // by name
    //

    cStmt.setInt("inOutParam", 1);

...
</pre></div></div><p><br class="example-break">
          </p></li><li class="listitem"><p>
            Execute the <code class="classname">CallableStatement</code>, and
            retrieve any result sets or output parameters.
          </p><p>
            Although <code class="classname">CallableStatement</code> supports
            calling any of the <code class="classname">Statement</code> execute
            methods (<code class="function">executeUpdate()</code>,
            <code class="function">executeQuery()</code> or
            <code class="function">execute()</code>), the most flexible method to
            call is <code class="function">execute()</code>, as you do not need
            to know ahead of time if the stored procedure returns result
            sets:

            </p><div class="example"><a name="connector-j-examples-retrieving-results-params"></a><p class="title"><b>Example 6.7 Connector/J: Retrieving results and output parameter values</b></p><div class="example-contents"><pre class="programlisting">
...

    boolean hadResults = cStmt.execute();

    //
    // Process all returned result sets
    //

    while (hadResults) {
        ResultSet rs = cStmt.getResultSet();

        // process result set
        ...

        hadResults = cStmt.getMoreResults();
    }

    //
    // Retrieve output parameters
    //
    // Connector/J supports both index-based and
    // name-based retrieval
    //

    int outputValue = cStmt.getInt(2); // index-based

    outputValue = cStmt.getInt("inOutParam"); // name-based

...
</pre></div></div><p><br class="example-break">
          </p></li></ol></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-last-insert-id"></a>6.4 Retrieving <code class="literal">AUTO_INCREMENT</code> Column Values through JDBC</h2></div></div></div><p>
        Before version 3.0 of the JDBC API, there was no standard way of
        retrieving key values from databases that supported auto
        increment or identity columns. With older JDBC drivers for
        MySQL, you could always use a MySQL-specific method on the
        <code class="classname">Statement</code> interface, or issue the query
        <code class="literal">SELECT LAST_INSERT_ID()</code> after issuing an
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/insert.html" target="_top"><code class="literal">INSERT</code></a> to a table that had an
        <code class="literal">AUTO_INCREMENT</code> key. Using the MySQL-specific
        method call isn't portable, and issuing a
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> to get the
        <code class="literal">AUTO_INCREMENT</code> key's value requires another
        round-trip to the database, which isn't as efficient as
        possible. The following code snippets demonstrate the three
        different ways to retrieve <code class="literal">AUTO_INCREMENT</code>
        values. First, we demonstrate the use of the new JDBC 3.0 method
        <code class="function">getGeneratedKeys()</code> which is now the
        preferred method to use if you need to retrieve
        <code class="literal">AUTO_INCREMENT</code> keys and have access to JDBC
        3.0. The second example shows how you can retrieve the same
        value using a standard <code class="literal">SELECT
        LAST_INSERT_ID()</code> query. The final example shows how
        updatable result sets can retrieve the
        <code class="literal">AUTO_INCREMENT</code> value when using the
        <code class="function">insertRow()</code> method.
      </p><div class="example"><a name="connector-j-examples-autoincrement-getgeneratedkeys"></a><p class="title"><b>Example 6.8 Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
          using <code class="literal">Statement.getGeneratedKeys()</code></b></p><div class="example-contents"><pre class="programlisting">
Statement stmt = null;
ResultSet rs = null;

try {

    //
    // Create a Statement instance that we can use for
    // 'normal' result sets assuming you have a
    // Connection 'conn' to a MySQL database already
    // available

    stmt = conn.createStatement();

    //
    // Issue the DDL queries for the table for this example
    //

    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
    stmt.executeUpdate(
            "CREATE TABLE autoIncTutorial ("
            + "priKey INT NOT NULL AUTO_INCREMENT, "
            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");

    //
    // Insert one row that will generate an AUTO INCREMENT
    // key in the 'priKey' field
    //

    stmt.executeUpdate(
            "INSERT INTO autoIncTutorial (dataField) "
            + "values ('Can I Get the Auto Increment Field?')",
            Statement.RETURN_GENERATED_KEYS);

    //
    // Example of using Statement.getGeneratedKeys()
    // to retrieve the value of an auto-increment
    // value
    //

    int autoIncKeyFromApi = -1;

    rs = stmt.getGeneratedKeys();

    if (rs.next()) {
        autoIncKeyFromApi = rs.getInt(1);
    } else {

        // throw an exception from here
    }

    System.out.println("Key returned from getGeneratedKeys():"
        + autoIncKeyFromApi);
} finally {

    if (rs != null) {
        try {
            rs.close();
        } catch (SQLException ex) {
            // ignore
        }
    }

    if (stmt != null) {
        try {
            stmt.close();
        } catch (SQLException ex) {
            // ignore
        }
    }
}
</pre></div></div><br class="example-break"><div class="example"><a name="connector-j-examples-autoincrement-select"></a><p class="title"><b>Example 6.9 Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
          using <code class="literal">SELECT LAST_INSERT_ID()</code></b></p><div class="example-contents"><pre class="programlisting">
Statement stmt = null;
ResultSet rs = null;

try {

    //
    // Create a Statement instance that we can use for
    // 'normal' result sets.

    stmt = conn.createStatement();

    //
    // Issue the DDL queries for the table for this example
    //

    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
    stmt.executeUpdate(
            "CREATE TABLE autoIncTutorial ("
            + "priKey INT NOT NULL AUTO_INCREMENT, "
            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");

    //
    // Insert one row that will generate an AUTO INCREMENT
    // key in the 'priKey' field
    //

    stmt.executeUpdate(
            "INSERT INTO autoIncTutorial (dataField) "
            + "values ('Can I Get the Auto Increment Field?')");

    //
    // Use the MySQL LAST_INSERT_ID()
    // function to do the same thing as getGeneratedKeys()
    //

    int autoIncKeyFromFunc = -1;
    rs = stmt.executeQuery("SELECT LAST_INSERT_ID()");

    if (rs.next()) {
        autoIncKeyFromFunc = rs.getInt(1);
    } else {
        // throw an exception from here
    }

    System.out.println("Key returned from " +
                       "'SELECT LAST_INSERT_ID()': " +
                       autoIncKeyFromFunc);

} finally {

    if (rs != null) {
        try {
            rs.close();
        } catch (SQLException ex) {
            // ignore
        }
    }

    if (stmt != null) {
        try {
            stmt.close();
        } catch (SQLException ex) {
            // ignore
        }
    }
}
</pre></div></div><br class="example-break"><div class="example"><a name="connector-j-examples-autoincrement-updateable-resultsets"></a><p class="title"><b>Example 6.10 Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
          in <code class="literal">Updatable ResultSets</code></b></p><div class="example-contents"><pre class="programlisting">
Statement stmt = null;
ResultSet rs = null;

try {

    //
    // Create a Statement instance that we can use for
    // 'normal' result sets as well as an 'updatable'
    // one, assuming you have a Connection 'conn' to
    // a MySQL database already available
    //

    stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
                                java.sql.ResultSet.CONCUR_UPDATABLE);

    //
    // Issue the DDL queries for the table for this example
    //

    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
    stmt.executeUpdate(
            "CREATE TABLE autoIncTutorial ("
            + "priKey INT NOT NULL AUTO_INCREMENT, "
            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");

    //
    // Example of retrieving an AUTO INCREMENT key
    // from an updatable result set
    //

    rs = stmt.executeQuery("SELECT priKey, dataField "
       + "FROM autoIncTutorial");

    rs.moveToInsertRow();

    rs.updateString("dataField", "AUTO INCREMENT here?");
    rs.insertRow();

    //
    // the driver adds rows at the end
    //

    rs.last();

    //
    // We should now be on the row we just inserted
    //

    int autoIncKeyFromRS = rs.getInt("priKey");

    System.out.println("Key returned for inserted row: "
        + autoIncKeyFromRS);

} finally {

    if (rs != null) {
        try {
            rs.close();
        } catch (SQLException ex) {
            // ignore
        }
    }

    if (stmt != null) {
        try {
            stmt.close();
        } catch (SQLException ex) {
            // ignore
        }
    }
}
</pre></div></div><br class="example-break"><p>
        Running the preceding example code should produce the following
        output:
      </p><pre class="programlisting">
Key returned from getGeneratedKeys(): 1
Key returned from SELECT LAST_INSERT_ID(): 1
Key returned for inserted row: 1
</pre><p>
        At times, it can be tricky to use the <code class="literal">SELECT
        LAST_INSERT_ID()</code> query, as that function's value is
        scoped to a connection. So, if some other query happens on the
        same connection, the value is overwritten. On the other hand,
        the <code class="function">getGeneratedKeys()</code> method is scoped by
        the <code class="classname">Statement</code> instance, so it can be used
        even if other queries happen on the same connection, but not on
        the same <code class="classname">Statement</code> instance.
      </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-j2ee-concepts-connection-pooling"></a>Chapter 7 Connection Pooling with Connector/J</h1></div></div></div><a class="indexterm" name="idm140410757567024"></a><a class="indexterm" name="idm140410757565632"></a><p>
      Connection pooling is a technique of creating and managing a pool
      of connections that are ready for use by any
      <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_thread" target="_top">thread</a> that needs them.
      Connection pooling can greatly increase the performance of your
      Java application, while reducing overall resource usage.
    </p><h2><a name="idm140410757563296"></a>How Connection Pooling Works</h2><p>
      Most applications only need a thread to have access to a JDBC
      connection when they are actively processing a
      <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_transaction" target="_top">transaction</a>, which often
      takes only milliseconds to complete. When not processing a
      transaction, the connection sits idle. Connection pooling enables
      the idle connection to be used by some other thread to do useful
      work.
    </p><p>
      In practice, when a thread needs to do work against a MySQL or
      other database with JDBC, it requests a connection from the pool.
      When the thread is finished using the connection, it returns it to
      the pool, so that it can be used by any other threads.
    </p><p>
      When the connection is loaned out from the pool, it is used
      exclusively by the thread that requested it. From a programming
      point of view, it is the same as if your thread called
      <code class="literal">DriverManager.getConnection()</code> every time it
      needed a JDBC connection. With connection pooling, your thread may
      end up using either a new connection or an already-existing
      connection.
    </p><h2><a name="idm140410757559072"></a>Benefits of Connection Pooling</h2><p>
      The main benefits to connection pooling are:
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Reduced connection creation time.
        </p><p>
          Although this is not usually an issue with the quick
          connection setup that MySQL offers compared to other
          databases, creating new JDBC connections still incurs
          networking and JDBC driver overhead that will be avoided if
          connections are recycled.
        </p></li><li class="listitem"><p>
          Simplified programming model.
        </p><p>
          When using connection pooling, each individual thread can act
          as though it has created its own JDBC connection, allowing you
          to use straightforward JDBC programming techniques.
        </p></li><li class="listitem"><p>
          Controlled resource usage.
        </p><p>
          If you create a new connection every time a thread needs one
          rather than using connection pooling, your application's
          resource usage can be wasteful, and it could lead to
          unpredictable behaviors for your application when it is under
          a heavy load.
        </p></li></ul></div><h2><a name="idm140410757553264"></a>Using Connection Pooling with Connector/J</h2><p>
      The concept of connection pooling in JDBC has been standardized
      through the JDBC 2.0 Optional interfaces, and all major
      application servers have implementations of these APIs that work
      with MySQL Connector/J.
    </p><p>
      Generally, you configure a connection pool in your application
      server configuration files, and access it through the Java Naming
      and Directory Interface (JNDI). The following code shows how you
      might use a connection pool from an application deployed in a J2EE
      application server:

      </p><div class="example"><a name="connector-j-examples-connectionpool-j2ee"></a><p class="title"><b>Example 7.1 Connector/J: Using a connection pool with a J2EE application server</b></p><div class="example-contents"><pre class="programlisting">
import java.sql.Connection;
import java.sql.SQLException;
import java.sql.Statement;

import javax.naming.InitialContext;
import javax.sql.DataSource;


public class MyServletJspOrEjb {

    public void doSomething() throws Exception {
        /*
         * Create a JNDI Initial context to be able to
         *  lookup  the DataSource
         *
         * In production-level code, this should be cached as
         * an instance or static variable, as it can
         * be quite expensive to create a JNDI context.
         *
         * Note: This code only works when you are using servlets
         * or EJBs in a J2EE application server. If you are
         * using connection pooling in standalone Java code, you
         * will have to create/configure datasources using whatever
         * mechanisms your particular connection pooling library
         * provides.
         */

        InitialContext ctx = new InitialContext();

         /*
          * Lookup the DataSource, which will be backed by a pool
          * that the application server provides. DataSource instances
          * are also a good candidate for caching as an instance
          * variable, as JNDI lookups can be expensive as well.
          */

        DataSource ds =
          (DataSource)ctx.lookup("java:comp/env/jdbc/MySQLDB");

        /*
         * The following code is what would actually be in your
         * Servlet, JSP or EJB 'service' method...where you need
         * to work with a JDBC connection.
         */

        Connection conn = null;
        Statement stmt = null;

        try {
            conn = ds.getConnection();

            /*
             * Now, use normal JDBC programming to work with
             * MySQL, making sure to close each resource when you're
             * finished with it, which permits the connection pool
             * resources to be recovered as quickly as possible
             */

            stmt = conn.createStatement();
            stmt.execute("SOME SQL QUERY");

            stmt.close();
            stmt = null;

            conn.close();
            conn = null;
        } finally {
            /*
             * close any jdbc instances here that weren't
             * explicitly closed during normal code path, so
             * that we don't 'leak' resources...
             */

            if (stmt != null) {
                try {
                    stmt.close();
                } catch (sqlexception sqlex) {
                    // ignore, as we can't do anything about it here
                }

                stmt = null;
            }

            if (conn != null) {
                try {
                    conn.close();
                } catch (sqlexception sqlex) {
                    // ignore, as we can't do anything about it here
                }

                conn = null;
            }
        }
    }
}
</pre></div></div><p><br class="example-break">

      As shown in the example above, after obtaining the JNDI
      <code class="literal">InitialContext</code>, and looking up the
      <code class="literal">DataSource</code>, the rest of the code follows
      familiar JDBC conventions.
    </p><p>
      When using connection pooling, always make sure that connections,
      and anything created by them (such as statements or result sets)
      are closed. This rule applies no matter what happens in your code
      (exceptions, flow-of-control, and so forth). When these objects
      are closed, they can be re-used; otherwise, they will be stranded,
      which means that the MySQL server resources they represent (such
      as buffers, locks, or sockets) are tied up for some time, or in
      the worst case can be tied up forever.
    </p><h2><a name="idm140410757541424"></a>Sizing the Connection Pool</h2><p>
      Each connection to MySQL has overhead (memory, CPU, context
      switches, and so forth) on both the client and server side. Every
      connection limits how many resources there are available to your
      application as well as the MySQL server. Many of these resources
      will be used whether or not the connection is actually doing any
      useful work! Connection pools can be tuned to maximize
      performance, while keeping resource utilization below the point
      where your application will start to fail rather than just run
      slower.
    </p><p>
      The optimal size for the connection pool depends on anticipated
      load and average database transaction time. In practice, the
      optimal connection pool size can be smaller than you might expect.
      If you take Oracle's Java Petstore blueprint application for
      example, a connection pool of 15-20 connections can serve a
      relatively moderate load (600 concurrent users) using MySQL and
      Tomcat with acceptable response times.
    </p><p>
      To correctly size a connection pool for your application, create
      load test scripts with tools such as Apache JMeter or The Grinder,
      and load test your application.
    </p><p>
      An easy way to determine a starting point is to configure your
      connection pool's maximum number of connections to be unbounded,
      run a load test, and measure the largest amount of concurrently
      used connections. You can then work backward from there to
      determine what values of minimum and maximum pooled connections
      give the best performance for your particular application.
    </p><h2><a name="idm140410757537552"></a>Validating Connections</h2><p>
      MySQL Connector/J can validate the connection by executing a
      lightweight ping against a server. In the case of load-balanced
      connections, this is performed against all active pooled internal
      connections that are retained. This is beneficial to Java
      applications using connection pools, as the pool can use this
      feature to validate connections. Depending on your connection pool
      and configuration, this validation can be carried out at different
      times:
    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
          Before the pool returns a connection to the application.
        </p></li><li class="listitem"><p>
          When the application returns a connection to the pool.
        </p></li><li class="listitem"><p>
          During periodic checks of idle connections.
        </p></li></ol></div><p>
      To use this feature, specify a validation query in your connection
      pool that starts with <code class="literal">/* ping */</code>. Note that the
      syntax must be exactly as specified. This will cause the driver
      send a ping to the server and return a dummy lightweight result
      set. When using a <code class="literal">ReplicationConnection</code> or
      <code class="literal">LoadBalancedConnection</code>, the ping will be sent
      across all active connections.
    </p><p>
      It is critical that the syntax be specified correctly. The syntax
      needs to be exact for reasons of efficiency, as this test is done
      for every statement that is executed:
    </p><pre class="programlisting">

protected static final String PING_MARKER = "/* ping */";
...
if (sql.charAt(0) == '/') {
if (sql.startsWith(PING_MARKER)) {
doPingInstead();
...

</pre><p>
      None of the following snippets will work, because the ping syntax
      is sensitive to whitespace, capitalization, and placement:
    </p><pre class="programlisting">
sql = "/* PING */ SELECT 1";
sql = "SELECT 1 /* ping*/";
sql = "/*ping*/ SELECT 1";
sql = " /* ping */ SELECT 1";
sql = "/*to ping or not to ping*/ SELECT 1";
</pre><p>
      All of the previous statements will issue a normal
      <code class="literal">SELECT</code> statement and will
      <span class="bold"><strong>not</strong></span> be transformed into the
      lightweight ping. Further, for load-balanced connections, the
      statement will be executed against one connection in the internal
      pool, rather than validating each underlying physical connection.
      This results in the non-active physical connections assuming a
      stale state, and they may die. If Connector/J then re-balances, it
      might select a dead connection, resulting in an exception being
      passed to the application. To help prevent this, you can use
      <code class="literal">loadBalanceValidateConnectionOnSwapServer</code> to
      validate the connection before use.
    </p><p>
      If your Connector/J deployment uses a connection pool that allows
      you to specify a validation query, take advantage of it, but
      ensure that the query starts <span class="emphasis"><em>exactly</em></span> with
      <code class="literal">/* ping */</code>. This is particularly important if
      you are using the load-balancing or replication-aware features of
      Connector/J, as it will help keep alive connections which
      otherwise will go stale and die, causing problems later.
    </p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-multi-host-connections"></a>Chapter 8 Multi-Host Connections</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-config-failover">8.1 Configuring Server Failover</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections">8.2 Configuring Load Balancing with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-master-slave-replication-connection">8.3 Configuring Master/Slave Replication with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover">8.4 Advanced Load-balancing and Failover Configuration</a></span></dt></dl></div><a class="indexterm" name="idm140410757521488"></a><p>
      The following sections discuss a number of topics that involve
      multi-host connections, namely, server load-balancing, failover,
      and replication.
    </p><p>
      Developers should know the following things about multi-host
      connections that are managed through Connector/J:

      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Each multi-host connection is a wrapper of the underlying
            physical connections.
          </p></li><li class="listitem"><p>
            Each of the underlying physical connections has its own
            session. Sessions cannot be tracked, shared, or copied,
            given the MySQL architecture.
          </p></li><li class="listitem"><p>
            Every switch between physical connections means a switch
            between sessions.
          </p></li><li class="listitem"><p>
            Within a transaction boundary, there are no switches between
            physical connections. Beyond a transaction boundary, there
            is no guarantee that a switch does not occur.
          </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
              If an application reuses session-scope data (for example,
              variables, SSPs) beyond a transaction boundary, failures
              are possible, as a switch between the physical connections
              (which is also a switch between sessions) might occur.
              Therefore, the application should re-prepare the session
              data and also restart the last transaction in case of an
              exception, or it should re-prepare session data for each
              new transaction if it does not want to deal with exception
              handling.
            </p></div></li></ul></div><p>
    </p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-config-failover"></a>8.1 Configuring Server Failover</h2></div></div></div><a class="indexterm" name="idm140410757512576"></a><p>
        MySQL Connector/J supports server failover. A failover happens
        when connection-related errors occur for an underlying, active
        connection. The connection errors are, by default, propagated to
        the client, which has to handle them by, for example, recreating
        the working objects (<code class="literal">Statement</code>,
        <code class="literal">ResultSet</code>, etc.) and restarting the
        processes. Sometimes, the driver might eventually fall back to
        the original host automatically before the client application
        continues to run, in which case the host switch is transparent
        and the client application will not even notice it.
      </p><p>
      </p><p>
        A connection using failover support works just like a standard
        connection: the client does not experience any disruptions in
        the failover process. This means the client can rely on the same
        connection instance even if two successive statements might be
        executed on two different physical hosts. However, this does not
        mean the client does not have to deal with the exception that
        triggered the server switch.
      </p><p>
        The failover is configured at the initial setup stage of the
        server connection by the connection URL (see explanations for
        its format
        <a class="link" href="#connector-j-reference-url-format" title="JDBC URL Format">here</a>):

</p><pre class="programlisting">
jdbc:mysql://[<em class="replaceable"><code>primary host</code></em>][:<em class="replaceable"><code>port</code></em>],[<em class="replaceable"><code>secondary host 1</code></em>][:<em class="replaceable"><code>port</code></em>][,[<em class="replaceable"><code>secondary host 2</code></em>][:<em class="replaceable"><code>port</code></em>]]...[/[<em class="replaceable"><code>database</code></em>]]»
[?<em class="replaceable"><code>propertyName1</code></em>=<em class="replaceable"><code>propertyValue1</code></em>[&amp;<em class="replaceable"><code>propertyName2</code></em>=<em class="replaceable"><code>propertyValue2</code></em>]...]
</pre><p>
      </p><p>
        The host list in the connection URL comprises of two types of
        hosts, the primary and the secondary. When starting a new
        connection, the driver always tries to connect to the primary
        host first and, if required, fails over to the secondary hosts
        on the list sequentially when communication problems are
        experienced. Even if the initial connection to the primary host
        fails and the driver gets connected to a secondary host, the
        primary host never loses its special status: for example, it can
        be configured with an access mode distinct from those of the
        secondary hosts, and it can be put on a higher priority when a
        host is to be picked during a failover process.
      </p><p>
        The failover support is configured by the following connection
        properties (their functions are explained in the paragraphs
        below):

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">failOverReadOnly</code>
            </p></li><li class="listitem"><p>
              <code class="literal">secondsBeforeRetryMaster</code>
            </p></li><li class="listitem"><p>
              <code class="literal">queriesBeforeRetryMaster</code>
            </p></li><li class="listitem"><p>
              <code class="literal">retriesAllDown</code>
            </p></li><li class="listitem"><p>
              <code class="literal">autoReconnect</code>
            </p></li><li class="listitem"><p>
              <code class="literal">autoReconnectForPools</code>
            </p></li></ul></div><p>
      </p><h3><a name="idm140410757490384"></a>Configuring Connection Access Mode</h3><p>
        As with any standard connection, the initial connection to the
        primary host is in read/write mode. However, if the driver fails
        to establish the initial connection to the primary host and it
        automatically switches to the next host on the list, the access
        mode now depends on the value of the property
        <code class="literal">failOverReadOnly</code>, which is
        <span class="quote">“<span class="quote">true</span>”</span> by default. The same happens if the driver
        is initially connected to the primary host and, because of some
        connection failure, it fails over to a secondary host. Every
        time the connection falls back to the primary host, its access
        mode will be read/write, irrespective of whether or not the
        primary host has been connected to before. The connection access
        mode can be changed any time at runtime by calling the
        method<code class="literal"> Connection.setReadOnly(boolean)</code>, which
        partially overrides the property
        <code class="literal">failOverReadOnly</code>. When
        <code class="literal">failOverReadOnly=false</code> and the access mode is
        explicitly set to either true or false, it becomes the mode for
        every connection after a host switch, no matter what host type
        are we connected to; but, if
        <code class="literal">failOverReadOnly=true</code>, changing the access
        mode to read/write is only possible if the driver is connecting
        to the primary host; however, even if the access mode cannot be
        changed for the current connection, the driver remembers the
        client's last intention and, when falling back to the primary
        host, that is the mode that will be used. For an illustration,
        see the following successions of events with a two-host
        connection.

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Sequence A, with <code class="literal">failOverReadOnly=true</code>:

              </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
                    Connects to primary host in read/write mode
                  </p></li><li class="listitem"><p>
                    Sets
                    <code class="literal">Connection.setReadOnly(true)</code>;
                    primary host now in read-only mode
                  </p></li><li class="listitem"><p>
                    Failover event; connects to secondary host in
                    read-only mode
                  </p></li><li class="listitem"><p>
                    Sets
                    <code class="literal">Connection.setReadOnly(false)</code>;
                    secondary host remains in read-only mode
                  </p></li><li class="listitem"><p>
                    Falls back to primary host; connection now in
                    read/write mode
                  </p></li></ol></div><p>
            </p></li><li class="listitem"><p>
              Sequence B, with <code class="literal">failOverReadOnly=false</code>
            </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
                  Connects to primary host in read/write mode
                </p></li><li class="listitem"><p>
                  Sets <code class="literal">Connection.setReadOnly(true)</code>;
                  primary host now in read-only mode
                </p></li><li class="listitem"><p>
                  Failover event; connects to secondary host in
                  read-only mode
                </p></li><li class="listitem"><p>
                  Set <code class="literal">Connection.setReadOnly(false)</code>;
                  connection to secondary host switches to read/write
                  mode
                </p></li><li class="listitem"><p>
                  Falls back to primary host; connection now in
                  read/write mode
                </p></li></ol></div></li></ul></div><p>
      </p><p>
        The difference between the two scenarios is in step 4: the
        access mode for the secondary host in sequence A does not change
        at that step, but the driver remembers and uses the set mode
        when falling back to the primary host, which would be read-only
        otherwise; but in sequence B, the access mode for the secondary
        host changes immediately.
      </p><h3><a name="idm140410757467216"></a>Configuring Fallback to Primary Host</h3><p>
        As already mentioned, the primary host is special in the
        failover arrangement when it comes to the host's access mode.
        Additionally, the driver tries to fall back to the primary host
        as soon as possible by default, even if no communication
        exception occurs. Two properties,
        <code class="literal">secondsBeforeRetryMaster</code> and
        <code class="literal">queriesBeforeRetryMaster</code>, determine when the
        driver is ready to retry a reconnection to the primary host (the
        <code class="literal">Master</code> in the property names stands for the
        primary host of our connection URL, which is not necessarily a
        master host in a replication setup; the naming was maintained
        for back compatibility with Connector/J versions prior to
        5.1.35):

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">secondsBeforeRetryMaster</code> determines how
              much time the driver waits before trying to fall back to
              the primary host
            </p></li><li class="listitem"><p>
              <code class="literal">queriesBeforeRetryMaster</code> determines the
              number of queries that are executed before the driver
              tries to fall back to the primary host. Note that for the
              driver, each call to a
              <code class="literal">Statement.execute*()</code> method increments
              the query execution counter; therefore, when calls are
              made to <code class="literal">Statement.executeBatch()</code> or if
              <code class="literal">allowMultiQueries</code> or
              <code class="literal">rewriteBatchStatements</code> are enabled, the
              driver may not have an accurate count of the actual number
              of queries executed on the server. Also, the driver calls
              the <code class="literal">Statement.execute*()</code> methods
              internally in several occasions. All these mean you can
              only use <code class="literal">queriesBeforeRetryMaster</code> only
              as a coarse specification for when to fall back to the
              primary host.
            </p></li></ul></div><p>

        In general, an attempt to fallback to the primary host is made
        when at least one of the conditions specified by the two
        properties is met, and the attempt always takes place at
        transaction boundaries. However, if auto-commit is turned off,
        the check happens only when the method
        <code class="literal">Connection.commit()</code> or
        <code class="literal">Connection.rollback()</code> is called. The
        automatic fallback to the primary host can be turned off by
        setting simultaneously
        <code class="literal">secondsBeforeRetryMaster</code> and
        <code class="literal">queriesBeforeRetryMaster</code> to <span class="quote">“<span class="quote">0</span>”</span>.
        Setting only one of the properties to <span class="quote">“<span class="quote">0</span>”</span> only
        disables one part of the check.
      </p><h3><a name="connector-j-config-reconnect"></a>Configuring Reconnection Attempts</h3><p>
        When establishing a new connection or when a failover event
        occurs, the driver tries to connect successively to the next
        candidate on the host list. When the end of the list has been
        reached, it restarts all over again from the beginning of the
        list; however, the primary host is skipped over, if (a) NOT all
        the secondary hosts have already been tested at least once, AND
        (b) the fallback conditions defined by
        <code class="literal">secondsBeforeRetryMaster</code> and
        <code class="literal">queriesBeforeRetryMaster</code> are not yet
        fulfilled. Each run-through of the whole host list, (which is
        not necessarily completed at the end of the host list) counts as
        a single connection attempt. The driver tries as many connection
        attempts as specified by the value of the property
        <code class="literal">retriesAllDown</code>.
      </p><h3><a name="idm140410757448064"></a>Seamless Reconnection</h3><p>
        Although not recommended, you can make the driver perform
        failovers without invalidating the active
        <code class="literal">Statement</code> or <code class="literal">ResultSet</code>
        instances by setting either the parameter
        <code class="literal">autoReconnect</code> or
        <code class="literal">autoReconnectForPools</code> to
        <code class="literal">true</code>. This allows the client to continue
        using the same object instances after a failover event, without
        taking any exceptional measures. This, however, may lead to
        unexpected results: for example, if the driver is connected to
        the primary host with read/write access mode and it fails-over
        to a secondary host in real-only mode, further attempts to issue
        data-changing queries will result in errors, and the client will
        not be aware of that. This limitation is particularly relevant
        when using data streaming: after the failover, the
        <code class="literal">ResultSet</code> looks to be alright, but the
        underlying connection may have changed already, and no backing
        cursor is available anymore.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections"></a>8.2 Configuring Load Balancing with Connector/J</h2></div></div></div><a class="indexterm" name="idm140410757441056"></a><a class="indexterm" name="idm140410757439664"></a><p>
        Connector/J has long provided an effective means to distribute
        read/write load across multiple MySQL server instances for
        Cluster or master-master replication deployments. Starting with
        Connector/J 5.1.3, you can now dynamically configure
        load-balanced connections, with no service outage. In-process
        transactions are not lost, and no application exceptions are
        generated if any application is trying to use that particular
        server instance.
      </p><p>
        The load balancing is configured at the initial setup stage of
        the server connection by the following connection URL, which has
        a similar format as
        <a class="link" href="#connector-j-reference-url-format" title="JDBC URL Format">the general URL
        for MySQL connection</a>, but a specialized scheme:

</p><pre class="programlisting">
jdbc:mysql:loadbalance://[<em class="replaceable"><code>host</code></em>1][:<em class="replaceable"><code>port</code></em>],[<em class="replaceable"><code>host</code></em>2][:<em class="replaceable"><code>port</code></em>][,[<em class="replaceable"><code>host</code></em>3][:<em class="replaceable"><code>port</code></em>]]...[/[<em class="replaceable"><code>database</code></em>]] »
[?<em class="replaceable"><code>propertyName1</code></em>=<em class="replaceable"><code>propertyValue1</code></em>[&amp;<em class="replaceable"><code>propertyName2</code></em>=<em class="replaceable"><code>propertyValue2</code></em>]...]
</pre><p>
      </p><p>
        There are two configuration properties associated with this
        functionality:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">loadBalanceConnectionGroup</code> – This
            provides the ability to group connections from different
            sources. This allows you to manage these JDBC sources within
            a single class loader in any combination you choose. If they
            use the same configuration, and you want to manage them as a
            logical single group, give them the same name. This is the
            key property for management: if you do not define a name
            (string) for <code class="literal">loadBalanceConnectionGroup</code>,
            you cannot manage the connections. All load-balanced
            connections sharing the same
            <code class="literal">loadBalanceConnectionGroup</code> value,
            regardless of how the application creates them, will be
            managed together.
          </p></li><li class="listitem"><p>
            <code class="literal">loadBalanceEnableJMX</code> – The ability to
            manage the connections is exposed when you define a
            <code class="literal">loadBalanceConnectionGroup</code>; but if you
            want to manage this externally, enable JMX by setting this
            property to <code class="literal">true</code>. This enables a JMX
            implementation, which exposes the management and monitoring
            operations of a connection group. Further, start your
            application with the
            <code class="literal">-Dcom.sun.management.jmxremote</code> JVM flag.
            You can then perform connect and perform operations using a
            JMX client such as <code class="literal">jconsole</code>.
          </p></li></ul></div><p>
        Once a connection has been made using the correct connection
        properties, a number of monitoring properties are available:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Current active host count.
          </p></li><li class="listitem"><p>
            Current active physical connection count.
          </p></li><li class="listitem"><p>
            Current active logical connection count.
          </p></li><li class="listitem"><p>
            Total logical connections created.
          </p></li><li class="listitem"><p>
            Total transaction count.
          </p></li></ul></div><p>
        The following management operations can also be performed:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Add host.
          </p></li><li class="listitem"><p>
            Remove host.
          </p></li></ul></div><p>
        The JMX interface,
        <code class="literal">com.mysql.jdbc.jmx.LoadBalanceConnectionGroupManagerMBean</code>,
        has the following methods:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">int getActiveHostCount(String group);</code>
          </p></li><li class="listitem"><p>
            <code class="literal">int getTotalHostCount(String group);</code>
          </p></li><li class="listitem"><p>
            <code class="literal">long getTotalLogicalConnectionCount(String
            group);</code>
          </p></li><li class="listitem"><p>
            <code class="literal">long getActiveLogicalConnectionCount(String
            group);</code>
          </p></li><li class="listitem"><p>
            <code class="literal">long getActivePhysicalConnectionCount(String
            group);</code>
          </p></li><li class="listitem"><p>
            <code class="literal">long getTotalPhysicalConnectionCount(String
            group);</code>
          </p></li><li class="listitem"><p>
            <code class="literal">long getTotalTransactionCount(String
            group);</code>
          </p></li><li class="listitem"><p>
            <code class="literal">void removeHost(String group, String host) throws
            SQLException;</code>
          </p></li><li class="listitem"><p>
            <code class="literal">void stopNewConnectionsToHost(String group, String
            host) throws SQLException;</code>
          </p></li><li class="listitem"><p>
            <code class="literal">void addHost(String group, String host, boolean
            forExisting);</code>
          </p></li><li class="listitem"><p>
            <code class="literal">String getActiveHostsList(String group);</code>
          </p></li><li class="listitem"><p>
            <code class="literal">String getRegisteredConnectionGroups();</code>
          </p></li></ul></div><p>
        The <code class="literal">getRegisteredConnectionGroups()</code> method
        returns the names of all connection groups defined in that class
        loader.
      </p><p>
        You can test this setup with the following code:
      </p><pre class="programlisting">

public class Test {

    private static String URL = "jdbc:mysql:loadbalance://" +
        "localhost:3306,localhost:3310/test?" +
        "loadBalanceConnectionGroup=first&amp;loadBalanceEnableJMX=true";

    public static void main(String[] args) throws Exception {
        new Thread(new Repeater()).start();
        new Thread(new Repeater()).start();
        new Thread(new Repeater()).start();
    }

    static Connection getNewConnection() throws SQLException, ClassNotFoundException {
        Class.forName("com.mysql.jdbc.Driver");
        return DriverManager.getConnection(URL, "root", "");
    }

    static void executeSimpleTransaction(Connection c, int conn, int trans){
        try {
            c.setAutoCommit(false);
            Statement s = c.createStatement();
            s.executeQuery("SELECT SLEEP(1) /* Connection: " + conn + ", transaction: " + trans + " */");
            c.commit();
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }

    public static class Repeater implements Runnable {
        public void run() {
            for(int i=0; i &lt; 100; i++){
                try {
                    Connection c = getNewConnection();
                    for(int j=0; j &lt; 10; j++){
                        executeSimpleTransaction(c, i, j);
                        Thread.sleep(Math.round(100 * Math.random()));
                    }
                    c.close();
                    Thread.sleep(100);
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
        }
    }
}

</pre><p>
        After compiling, the application can be started with the
        <code class="literal">-Dcom.sun.management.jmxremote</code> flag, to
        enable remote management. <code class="literal">jconsole</code> can then
        be started. The <code class="literal">Test</code> main class will be
        listed by <code class="literal">jconsole</code>. Select this and click
        <span class="guibutton">Connect</span>. You can then navigate to the
        <code class="literal">com.mysql.jdbc.jmx.LoadBalanceConnectionGroupManager</code>
        bean. At this point, you can click on various operations and
        examine the returned result.
      </p><p>
        If you now had an additional instance of MySQL running on port
        3309, you could ensure that Connector/J starts using it by using
        the <code class="literal">addHost()</code>, which is exposed in
        <code class="literal">jconsole</code>. Note that these operations can be
        performed dynamically without having to stop the application
        running.
      </p><p>
        For further information on the combination of load balancing and
        failover, see
        <a class="xref" href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover" title="8.4 Advanced Load-balancing and Failover Configuration">Section 8.4, “Advanced Load-balancing and Failover Configuration”</a>.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-master-slave-replication-connection"></a>8.3 Configuring Master/Slave Replication with Connector/J</h2></div></div></div><a class="indexterm" name="idm140410757382528"></a><a class="indexterm" name="idm140410757381136"></a><p>
        This section describe a number of features of Connector/J's
        support for replication-aware deployments.

        
      </p><p>
        The replication is configured at the initial setup stage of the
        server connection by the connection URL, which has a similar
        format as <a class="link" href="#connector-j-reference-url-format" title="JDBC URL Format">the
        general URL for MySQL connection</a>, but a specialized
        scheme:

</p><pre class="programlisting">
jdbc:mysql:replication://[<em class="replaceable"><code>master host</code></em>][:<em class="replaceable"><code>port</code></em>],[<em class="replaceable"><code>slave host 1</code></em>][:<em class="replaceable"><code>port</code></em>][,[<em class="replaceable"><code>slave host 2</code></em>][:<em class="replaceable"><code>port</code></em>]]...[/[<em class="replaceable"><code>database</code></em>]] »
[?<em class="replaceable"><code>propertyName1</code></em>=<em class="replaceable"><code>propertyValue1</code></em>[&amp;<em class="replaceable"><code>propertyName2</code></em>=<em class="replaceable"><code>propertyValue2</code></em>]...]
</pre><p>
      </p><h3><a name="idm140410757372704"></a>Scaling out Read Load by Distributing Read Traffic to Slaves</h3><p>
        Connector/J 3.1.7 and higher includes a variant of the driver
        that will automatically send queries to a read/write master, or
        a failover or round-robin loadbalanced set of slaves based on
        the state of <code class="literal">Connection.getReadOnly()</code>.
      </p><p>
        An application signals that it wants a transaction to be
        read-only by calling
        <code class="literal">Connection.setReadOnly(true)</code>. The
        replication-aware connection will use one of the slave
        connections, which are load-balanced per-virtual-machine using a
        round-robin scheme (a given connection is sticky to a slave
        unless that slave is removed from service). If you have a write
        transaction, or if you have a read that is time-sensitive
        (remember, replication in MySQL is asynchronous), set the
        connection to be not read-only, by calling
        <code class="literal">Connection.setReadOnly(false)</code> and the driver
        will ensure that further calls are sent to the master MySQL
        server. The driver takes care of propagating the current state
        of autocommit, isolation level, and catalog between all of the
        connections that it uses to accomplish this load balancing
        functionality.
      </p><p>
        To enable this functionality, use the
        <code class="literal">com.mysql.jdbc.ReplicationDriver</code> class when
        configuring your application server's connection pool or when
        creating an instance of a JDBC driver for your standalone
        application. Because it accepts the same URL format as the
        standard MySQL JDBC driver, <code class="literal">ReplicationDriver</code>
        does not currently work with
        <code class="literal">java.sql.DriverManager</code>-based connection
        creation unless it is the only MySQL JDBC driver registered with
        the <code class="literal">DriverManager</code> .
      </p><p>
        Here is a short example of how
        <code class="literal">ReplicationDriver</code> might be used in a
        standalone application:
      </p><a name="connector-j-using-replication-driver-example"></a><pre class="programlisting">
import java.sql.Connection;
import java.sql.ResultSet;
import java.util.Properties;

import com.mysql.jdbc.ReplicationDriver;

public class ReplicationDriverDemo {

  public static void main(String[] args) throws Exception {
    ReplicationDriver driver = new ReplicationDriver();

    Properties props = new Properties();

    // We want this for failover on the slaves
    props.put("autoReconnect", "true");

    // We want to load balance between the slaves
    props.put("roundRobinLoadBalance", "true");

    props.put("user", "foo");
    props.put("password", "bar");

    //
    // Looks like a normal MySQL JDBC url, with a
    // comma-separated list of hosts, the first
    // being the 'master', the rest being any number
    // of slaves that the driver will load balance against
    //

    Connection conn =
        driver.connect("jdbc:mysql:replication://master,slave1,slave2,slave3/test",
            props);

    //
    // Perform read/write work on the master
    // by setting the read-only flag to "false"
    //

    conn.setReadOnly(false);
    conn.setAutoCommit(false);
    conn.createStatement().executeUpdate("UPDATE some_table ....");
    conn.commit();

    //
    // Now, do a query from a slave, the driver automatically picks one
    // from the list
    //

    conn.setReadOnly(true);

    ResultSet rs =
      conn.createStatement().executeQuery("SELECT a,b FROM alt_table");

     .......
  }
}
</pre><p>
        Consider using the Load Balancing JDBC Pool
        (<span class="command"><strong>lbpool</strong></span>) tool, which provides a wrapper
        around the standard JDBC driver and enables you to use DB
        connection pools that includes checks for system failures and
        uneven load distribution. For more information, see
        <a class="ulink" href="http://code.google.com/p/mysql-lbpool/" target="_top">Load
        Balancing JDBC Driver for MySQL (mysql-lbpool)</a>.
      </p><h3><a name="connector-j-multiple-master-replication"></a>Support for Multiple-Master Replication Topographies</h3><p>
        Since Connector/J 5.1.27, multi-master replication topographies
        are supported.
      </p><p>
        The connection URL for replication discussed earlier (i.e., in
        the format of
        <code class="literal">jdbc:mysql:replication://master,slave1,slave2,slave3/test</code>)
        assumes that the first (and only the first) host is the master.
        Supporting deployments with an arbitrary number of masters and
        slaves requires a different URL syntax for specifying the hosts
        and the properties for specific hosts, which is just an
        expansion of the URL syntax discussed in
        <a class="xref" href="#connector-j-reference-ipv6-url" title="IPv6 Connections">IPv6 Connections</a> with the
        property <code class="literal">type=[master|slave]</code>; for example:

</p><pre class="programlisting">jdbc:mysql://address=(type=master)(host=master1host),address=(type=master)(host=master2host),address=(type=slave)(host=slave1host)/database</pre><p>
      </p><p>
        Connector/J uses a load-balanced connection internally for
        management of the master connections, which means that
        <code class="literal">ReplicationConnection</code>, when configured to use
        multiple masters, exposes the same options to balance load
        across master hosts as described in
        <a class="xref" href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections" title="8.2 Configuring Load Balancing with Connector/J">Section 8.2, “Configuring Load Balancing with Connector/J”</a>.
      </p><p>
        Users may specify the property<code class="literal">
        allowMasterDownConnections=true</code> to allow
        <code class="literal">Connection</code> objects to be created even though
        no master hosts are reachable. Such
        <code class="literal">Connection</code> objects report they are read-only,
        and <code class="literal">isMasterConnection()</code> returns false for
        them. The <code class="literal">Connection</code> tests for available
        master hosts when
        <code class="literal">Connection.setReadOnly(false)</code> is called,
        throwing an SQLException if it cannot establish a connection to
        a master, or switching to a master connection if the host is
        available.
      </p><h3><a name="idm140410757346720"></a>Live Reconfiguration of Replication Topography</h3><p><a name="connector-j-live-reconfiguration-replication"></a>
        Since Connector/J 5.1.28, live management of replication host
        (single or multi-master) topographies is also supported. This
        enables users to promote slaves for Java applications without
        requiring an application restart.
      </p><p>
        The replication hosts are most effectively managed in the
        context of a replication connection group. A
        ReplicationConnectionGroup class represents a logical grouping
        of connections which can be managed together. There may be one
        or more such replication connection groups in a given Java class
        loader (there can be an application with two different JDBC
        resources needing to be managed independently). This key class
        exposes host management methods for replication connections, and
        <code class="literal">ReplicationConnection</code> objects register
        themselves with the appropriate
        <code class="literal">ReplicationConnectionGroup</code> if a value for the
        new <code class="literal">replicationConnectionGroup</code> property is
        specified. The <code class="literal">ReplicationConnectionGroup</code>
        object tracks these connections until they are closed, and it is
        used to manipulate the hosts associated with these connections.
      </p><p>
        Some important methods related to host management include:

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">getMasterHosts()</code>: Returns a collection
              of strings representing the hosts configured as masters
            </p></li><li class="listitem"><p>
              <code class="literal">getSlaveHosts()</code>: Returns a collection
              of strings representing the hosts configured as slaves
            </p></li><li class="listitem"><p>
              <code class="literal">addSlaveHost(String host)</code>: Adds new
              host to pool of possible slave hosts for selection at
              start of new read-only workload
            </p></li><li class="listitem"><p>
              <code class="literal">promoteSlaveToMaster(String host)</code>:
              Removes the host from the pool of potential slaves for
              future read-only processes (existing read-only process is
              allowed to continue to completion) and adds the host to
              the pool of potential master hosts
            </p></li><li class="listitem"><p>
              <code class="literal">removeSlaveHost(String host, boolean
              closeGently)</code>: Removes the host (host name match
              must be exact) from the list of configured slaves; if
              <code class="literal">closeGently</code> is false, existing
              connections which have this host as currently active will
              be closed hardly (application should expect exceptions)
            </p></li><li class="listitem"><p>
              <code class="literal">removeMasterHost(String host, boolean
              closeGently)</code>: Same as
              <code class="literal">removeSlaveHost()</code>, but removes the host
              from the list of configured masters
            </p></li></ul></div><p>
      </p><p>
        Some useful management metrics include:

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">getConnectionCountWithHostAsSlave(String
              host)</code>: Returns the number of
              ReplicationConnection objects that have the given host
              configured as a possible slave
            </p></li><li class="listitem"><p>
              <code class="literal"> getConnectionCountWithHostAsMaster(String
              host)</code>: Returns the number of
              ReplicationConnection objects that have the given host
              configured as a possible master
            </p></li><li class="listitem"><p>
              <code class="literal">getNumberOfSlavesAdded()</code>: Returns the
              number of times a slave host has been dynamically added to
              the group pool
            </p></li><li class="listitem"><p>
              <code class="literal">getNumberOfSlavesRemoved()</code>: Returns the
              number of times a slave host has been dynamically removed
              from the group pool
            </p></li><li class="listitem"><p>
              <code class="literal">getNumberOfSlavePromotions()</code>: Returns
              the number of times a slave host has been promoted to a
              master
            </p></li><li class="listitem"><p>
              <code class="literal">getTotalConnectionCount()</code>: Returns the
              number of ReplicationConnection objects which have been
              registered with this group
            </p></li><li class="listitem"><p>
              <code class="literal">getActiveConnectionCount()</code>: Returns the
              number of ReplicationConnection objects currently being
              managed by this group
            </p></li></ul></div><p>
      </p><h3><a name="idm140410757317792"></a>ReplicationConnectionGroupManager</h3><p>
        <code class="literal">com.mysql.jdbc.ReplicationConnectionGroupManager</code>
        provides access to the replication connection groups, together
        with some utility methods.

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">getConnectionGroup(String groupName)</code>:
              Returns the <code class="literal">ReplicationConnectionGroup</code>
              object matching the groupName provided
            </p></li></ul></div><p>
      </p><p>
        The other methods in
        <code class="literal">ReplicationConnectionGroupManager</code> mirror
        those of <code class="literal">ReplicationConnectionGroup</code>, except
        that the first argument is a String group name. These methods
        will operate on all matching ReplicationConnectionGroups, which
        are helpful for removing a server from service and have it
        decommissioned across all possible
        <code class="literal">ReplicationConnectionGroups</code>.
      </p><p>
        These methods might be useful for in-JVM management of
        replication hosts if an application triggers topography changes.
        For managing host configurations from outside the JVM, JMX can
        be used.
      </p><h3><a name="idm140410757310384"></a>Using JMX for Managing Replication Hosts</h3><p>
        When Connector/J is started with
        <code class="literal">replicationEnableJMX=true</code> and a value set for
        the property <code class="literal">replicationConnectionGroup</code>, a
        JMX MBean will be registered, allowing manipulation of
        replication hosts by a JMX client. The MBean interface is
        defined in
        <code class="literal">com.mysql.jdbc.jmx.ReplicationGroupManagerMBean</code>,
        and leverages the
        <code class="literal">ReplicationConnectionGroupManager</code> static
        methods:
      </p><pre class="programlisting">
 public abstract void addSlaveHost(String groupFilter, String host) throws SQLException;
 public abstract void removeSlaveHost(String groupFilter, String host) throws SQLException;
 public abstract void promoteSlaveToMaster(String groupFilter, String host) throws SQLException;
 public abstract void removeMasterHost(String groupFilter, String host) throws SQLException;
 public abstract String getMasterHostsList(String group);
 public abstract String getSlaveHostsList(String group);
 public abstract String getRegisteredConnectionGroups();
 public abstract int getActiveMasterHostCount(String group);
 public abstract int getActiveSlaveHostCount(String group);
 public abstract int getSlavePromotionCount(String group);
 public abstract long getTotalLogicalConnectionCount(String group);
 public abstract long getActiveLogicalConnectionCount(String group);
</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-j2ee-concepts-load-balancing-failover"></a>8.4 Advanced Load-balancing and Failover Configuration</h2></div></div></div><p>
        Connector/J provides a useful load-balancing implementation for
        MySQL Cluster or multi-master deployments, as explained in
        <a class="xref" href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections" title="8.2 Configuring Load Balancing with Connector/J">Section 8.2, “Configuring Load Balancing with Connector/J”</a>
        and
        <a class="xref" href="#connector-j-multiple-master-replication" title="Support for Multiple-Master Replication Topographies">Support for Multiple-Master Replication Topographies</a>.
        As of Connector/J 5.1.12, this same implementation is used for
        balancing load between read-only slaves with
        <code class="literal">ReplicationDriver</code>.
      </p><p>
        When trying to balance workload between multiple servers, the
        driver has to determine when it is safe to swap servers, doing
        so in the middle of a transaction, for example, could cause
        problems. It is important not to lose state information. For
        this reason, Connector/J will only try to pick a new server when
        one of the following happens:
      </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
            At transaction boundaries (transactions are explicitly
            committed or rolled back).
          </p></li><li class="listitem"><p>
            A communication exception (SQL State starting with "08") is
            encountered.
          </p></li><li class="listitem"><p>
            When a <code class="literal">SQLException</code> matches conditions
            defined by user, using the extension points defined by the
            <code class="literal">loadBalanceSQLStateFailover</code>,
            <code class="literal">loadBalanceSQLExceptionSubclassFailover</code>
            or <code class="literal">loadBalanceExceptionChecker</code>
            properties.
          </p></li></ol></div><p>
        The third condition revolves around three new properties
        introduced with Connector/J 5.1.13. It allows you to control
        which <code class="literal">SQLException</code>s trigger failover.
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">loadBalanceExceptionChecker</code> - The
            <code class="literal">loadBalanceExceptionChecker</code> property is
            really the key. This takes a fully-qualified class name
            which implements the new
            <code class="literal">com.mysql.jdbc.LoadBalanceExceptionChecker</code>
            interface. This interface is very simple, and you only need
            to implement the following method:
          </p><pre class="programlisting">
public boolean shouldExceptionTriggerFailover(SQLException ex)
</pre><p>
            A <code class="literal">SQLException</code> is passed in, and a
            boolean returned. A value of <code class="literal">true</code>
            triggers a failover, <code class="literal">false</code> does not.
          </p><p>
            You can use this to implement your own custom logic. An
            example where this might be useful is when dealing with
            transient errors when using MySQL Cluster, where certain
            buffers may become overloaded. The following code snippet
            illustrates this:
          </p><pre class="programlisting">

public class NdbLoadBalanceExceptionChecker
 extends StandardLoadBalanceExceptionChecker {

 public boolean shouldExceptionTriggerFailover(SQLException ex) {
  return super.shouldExceptionTriggerFailover(ex)
    ||  checkNdbException(ex);
 }

 private boolean checkNdbException(SQLException ex){
 // Have to parse the message since most NDB errors
 // are mapped to the same DEMC.
  return (ex.getMessage().startsWith("Lock wait timeout exceeded") ||
  (ex.getMessage().startsWith("Got temporary error")
  &amp;&amp; ex.getMessage().endsWith("from NDB")));
 }
}

</pre><p>
            The code above extends
            <code class="literal">com.mysql.jdbc.StandardLoadBalanceExceptionChecker</code>,
            which is the default implementation. There are a few
            convenient shortcuts built into this, for those who want to
            have some level of control using properties, without writing
            Java code. This default implementation uses the two
            remaining properties:
            <code class="literal">loadBalanceSQLStateFailover</code> and
            <code class="literal">loadBalanceSQLExceptionSubclassFailover</code>.
          </p></li><li class="listitem"><p>
            <code class="literal">loadBalanceSQLStateFailover</code> - allows you
            to define a comma-delimited list of
            <code class="literal">SQLState</code> code prefixes, against which a
            <code class="literal">SQLException</code> is compared. If the prefix
            matches, failover is triggered. So, for example, the
            following would trigger a failover if a given
            <code class="literal">SQLException</code> starts with "00", or is
            "12345":
          </p><pre class="programlisting">
loadBalanceSQLStateFailover=00,12345
</pre></li><li class="listitem"><p>
            <code class="literal">loadBalanceSQLExceptionSubclassFailover</code> -
            can be used in conjunction with
            <code class="literal">loadBalanceSQLStateFailover</code> or on its
            own. If you want certain subclasses of
            <code class="literal">SQLException</code> to trigger failover, simply
            provide a comma-delimited list of fully-qualified class or
            interface names to check against. For example, if you want
            all <code class="literal">SQLTransientConnectionExceptions</code> to
            trigger failover, you would specify:
          </p><pre class="programlisting">
loadBalanceSQLExceptionSubclassFailover=java.sql.SQLTransientConnectionException
</pre></li></ul></div><p>
        While the three failover conditions enumerated earlier suit most
        situations, if <code class="literal">autocommit</code> is enabled,
        Connector/J never re-balances, and continues using the same
        physical connection. This can be problematic, particularly when
        load-balancing is being used to distribute read-only load across
        multiple slaves. However, Connector/J can be configured to
        re-balance after a certain number of statements are executed,
        when <code class="literal">autocommit</code> is enabled. This
        functionality is dependent upon the following properties:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">loadBalanceAutoCommitStatementThreshold</code>
            – defines the number of matching statements which will
            trigger the driver to potentially swap physical server
            connections. The default value, 0, retains the behavior that
            connections with <code class="literal">autocommit</code> enabled are
            never balanced.
          </p></li><li class="listitem"><p>
            <code class="literal">loadBalanceAutoCommitStatementRegex</code> –
            the regular expression against which statements must match.
            The default value, blank, matches all statements. So, for
            example, using the following properties will cause
            Connector/J to re-balance after every third statement that
            contains the string <span class="quote">“<span class="quote">test</span>”</span>:
          </p><pre class="programlisting">
loadBalanceAutoCommitStatementThreshold=3
loadBalanceAutoCommitStatementRegex=.*test.*
</pre><p>
            <code class="literal">loadBalanceAutoCommitStatementRegex</code> can
            prove useful in a number of situations. Your application may
            use temporary tables, server-side session state variables,
            or connection state, where letting the driver arbitrarily
            swap physical connections before processing is complete
            could cause data loss or other problems. This allows you to
            identify a trigger statement that is only executed when it
            is safe to swap physical connections.
          </p></li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-interceptors"></a>Chapter 9 Using the Connector/J Interceptor Classes</h1></div></div></div><p>
      An interceptor is a software design pattern that provides a
      transparent way to extend or modify some aspect of a program,
      similar to a user exit. No recompiling is required. With
      Connector/J, the interceptors are enabled and disabled by updating
      the connection string to refer to different sets of interceptor
      classes that you instantiate.
    </p><p>
      The connection properties that control the interceptors are
      explained in
      <a class="xref" href="#connector-j-reference-configuration-properties" title="5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
        for Connector/J”</a>:
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">connectionLifecycleInterceptors</code>, where you
          specify the fully qualified names of classes that implement
          the
          <code class="literal">com.mysql.jdbc.ConnectionLifecycleInterceptor</code>
          interface. In these kinds of interceptor classes, you might
          log events such as rollbacks, measure the time between
          transaction start and end, or count events such as calls to
          <code class="literal">setAutoCommit()</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">exceptionInterceptors</code>, where you specify
          the fully qualified names of classes that implement the
          <code class="literal">com.mysql.jdbc.ExceptionInterceptor</code>
          interface. In these kinds of interceptor classes, you might
          add extra diagnostic information to exceptions that can have
          multiple causes or indicate a problem with server settings.
          Because <code class="literal">exceptionInterceptors</code> classes are
          only called when handling a <code class="literal">SQLException</code>
          thrown from Connector/J code, they can be used even in
          production deployments without substantial performance
          overhead.
        </p></li><li class="listitem"><p>
          <code class="literal">statementInterceptors</code>, where you specify
          the fully qualified names of classes that implement the
          <code class="literal">com.mysql.jdbc.StatementInterceptorV2</code>
          interface. In these kinds of interceptor classes, you might
          change or augment the processing done by certain kinds of
          statements, such as automatically checking for queried data in
          a <span class="command"><strong>memcached</strong></span> server, rewriting slow queries,
          logging information about statement execution, or route
          requests to remote servers.
        </p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-tomcat"></a>Chapter 10 Using Connector/J with Tomcat</h1></div></div></div><a class="indexterm" name="idm140410757249248"></a><p>
      The following instructions are based on the instructions for
      Tomcat-5.x, available at
      <a class="ulink" href="http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html" target="_top">http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html</a>
      which is current at the time this document was written.
    </p><p>
      First, install the <code class="filename">.jar</code> file that comes with
      Connector/J in <code class="filename">$CATALINA_HOME/common/lib</code> so
      that it is available to all applications installed in the
      container.
    </p><p>
      Next, configure the JNDI DataSource by adding a declaration
      resource to <code class="filename">$CATALINA_HOME/conf/server.xml</code> in
      the context that defines your web application:
    </p><pre class="programlisting">
  &lt;Context ....&gt;

  ...

  &lt;Resource name="jdbc/MySQLDB"
               auth="Container"
               type="javax.sql.DataSource"/&gt;

  &lt;ResourceParams name="jdbc/MySQLDB"&gt;
    &lt;parameter&gt;
      &lt;name&gt;factory&lt;/name&gt;
      &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
      &lt;name&gt;maxActive&lt;/name&gt;
      &lt;value&gt;10&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
      &lt;name&gt;maxIdle&lt;/name&gt;
      &lt;value&gt;5&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
      &lt;name&gt;validationQuery&lt;/name&gt;
      &lt;value&gt;SELECT 1&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
      &lt;name&gt;testOnBorrow&lt;/name&gt;
      &lt;value&gt;true&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
      &lt;name&gt;testWhileIdle&lt;/name&gt;
      &lt;value&gt;true&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
      &lt;name&gt;timeBetweenEvictionRunsMillis&lt;/name&gt;
      &lt;value&gt;10000&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
      &lt;name&gt;minEvictableIdleTimeMillis&lt;/name&gt;
      &lt;value&gt;60000&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
     &lt;name&gt;username&lt;/name&gt;
     &lt;value&gt;someuser&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
     &lt;name&gt;password&lt;/name&gt;
     &lt;value&gt;somepass&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
       &lt;name&gt;driverClassName&lt;/name&gt;
       &lt;value&gt;com.mysql.jdbc.Driver&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;parameter&gt;
      &lt;name&gt;url&lt;/name&gt;
      &lt;value&gt;jdbc:mysql://localhost:3306/test&lt;/value&gt;
    &lt;/parameter&gt;

  &lt;/ResourceParams&gt;
&lt;/Context&gt;
</pre><p>
      Note that Connector/J 5.1.3 introduced a facility whereby, rather
      than use a <code class="literal">validationQuery</code> value of
      <code class="literal">SELECT 1</code>, it is possible to use
      <code class="literal">validationQuery</code> with a value set to <code class="literal">/*
      ping */</code>. This sends a ping to the server which then
      returns a fake result set. This is a lighter weight solution. It
      also has the advantage that if using
      <code class="literal">ReplicationConnection</code> or
      <code class="literal">LoadBalancedConnection</code> type connections, the
      ping will be sent across all active connections. The following XML
      snippet illustrates how to select this option:
    </p><pre class="programlisting">

&lt;parameter&gt;
 &lt;name&gt;validationQuery&lt;/name&gt;
 &lt;value&gt;/* ping */&lt;/value&gt;
&lt;/parameter&gt;

</pre><p>
      Note that <code class="literal">/* ping */</code> has to be specified
      exactly.
    </p><p>
      In general, follow the installation instructions that come with
      your version of Tomcat, as the way you configure datasources in
      Tomcat changes from time to time, and if you use the wrong syntax
      in your XML file, you will most likely end up with an exception
      similar to the following:
    </p><pre class="programlisting">
Error: java.sql.SQLException: Cannot load JDBC driver class 'null ' SQL
state: null 
</pre><p>
      Note that the auto-loading of drivers having the
      <code class="filename">META-INF/service/java.sql.Driver</code> class in
      JDBC 4.0 causes an improper undeployment of the Connector/J driver
      in Tomcat on Windows. Namely, the Connector/J jar remains locked.
      This is an initialization problem that is not related to the
      driver. The possible workarounds, if viable, are as follows: use
      "<code class="literal">antiResourceLocking=true</code>" as a Tomcat Context
      attribute, or remove the <code class="filename">META-INF/</code> directory.
    </p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-jboss"></a>Chapter 11 Using Connector/J with JBoss</h1></div></div></div><a class="indexterm" name="idm140410757229536"></a><p>
      These instructions cover JBoss-4.x. To make the JDBC driver
      classes available to the application server, copy the
      <code class="filename">.jar</code> file that comes with Connector/J to the
      <code class="filename">lib</code> directory for your server configuration
      (which is usually called <code class="filename">default</code>). Then, in
      the same configuration directory, in the subdirectory named
      deploy, create a datasource configuration file that ends with
      <code class="literal">-ds.xml</code>, which tells JBoss to deploy this file
      as a JDBC Datasource. The file should have the following contents:
    </p><pre class="programlisting">
&lt;datasources&gt;
    &lt;local-tx-datasource&gt;

        &lt;jndi-name&gt;MySQLDB&lt;/jndi-name&gt;
        &lt;connection-url&gt;jdbc:mysql://localhost:3306/dbname&lt;/connection-url&gt;
        &lt;driver-class&gt;com.mysql.jdbc.Driver&lt;/driver-class&gt;
        &lt;user-name&gt;user&lt;/user-name&gt;
        &lt;password&gt;pass&lt;/password&gt;

        &lt;min-pool-size&gt;5&lt;/min-pool-size&gt;

        &lt;max-pool-size&gt;20&lt;/max-pool-size&gt;

        &lt;idle-timeout-minutes&gt;5&lt;/idle-timeout-minutes&gt;

        &lt;exception-sorter-class-name&gt;
  com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
        &lt;/exception-sorter-class-name&gt;
        &lt;valid-connection-checker-class-name&gt;
  com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
        &lt;/valid-connection-checker-class-name&gt;

    &lt;/local-tx-datasource&gt;
&lt;/datasources&gt; 
</pre></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-spring-config"></a>Chapter 12 Using Connector/J with Spring</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-jdbctemplate">12.1 Using <code class="classname">JdbcTemplate</code></a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-transactional">12.2 Transactional JDBC Access</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-connpooling">12.3 Connection Pooling with Spring</a></span></dt></dl></div><a class="indexterm" name="idm140410757222304"></a><p>
      The Spring Framework is a Java-based application framework
      designed for assisting in application design by providing a way to
      configure components. The technique used by Spring is a well known
      design pattern called Dependency Injection (see
      <a class="ulink" href="http://www.martinfowler.com/articles/injection.html" target="_top">Inversion
      of Control Containers and the Dependency Injection
      pattern</a>). This article will focus on Java-oriented access
      to MySQL databases with Spring 2.0. For those wondering, there is
      a .NET port of Spring appropriately named Spring.NET.
    </p><p>
      Spring is not only a system for configuring components, but also
      includes support for aspect oriented programming (AOP). This is
      one of the main benefits and the foundation for Spring's resource
      and transaction management. Spring also provides utilities for
      integrating resource management with JDBC and Hibernate.
    </p><p>
      For the examples in this section the MySQL world sample database
      will be used. The first task is to set up a MySQL data source
      through Spring. Components within Spring use the
      <span class="quote">“<span class="quote">bean</span>”</span> terminology. For example, to configure a
      connection to a MySQL server supporting the world sample database,
      you might use:
    </p><pre class="programlisting">

&lt;util:map id="dbProps"&gt;
    &lt;entry key="db.driver" value="com.mysql.jdbc.Driver"/&gt;
    &lt;entry key="db.jdbcurl" value="jdbc:mysql://localhost/world"/&gt;
    &lt;entry key="db.username" value="myuser"/&gt;
    &lt;entry key="db.password" value="mypass"/&gt;
&lt;/util:map&gt;

</pre><p>
      In the above example, we are assigning values to properties that
      will be used in the configuration. For the datasource
      configuration:
    </p><pre class="programlisting">

&lt;bean id="dataSource"
       class="org.springframework.jdbc.datasource.DriverManagerDataSource"&gt;
    &lt;property name="driverClassName" value="${db.driver}"/&gt;
    &lt;property name="url" value="${db.jdbcurl}"/&gt;
    &lt;property name="username" value="${db.username}"/&gt;
    &lt;property name="password" value="${db.password}"/&gt;
&lt;/bean&gt;

</pre><p>
      The placeholders are used to provide values for properties of this
      bean. This means that you can specify all the properties of the
      configuration in one place instead of entering the values for each
      property on each bean. We do, however, need one more bean to pull
      this all together. The last bean is responsible for actually
      replacing the placeholders with the property values.
    </p><pre class="programlisting">

&lt;bean
 class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"&gt;
    &lt;property name="properties" ref="dbProps"/&gt;
&lt;/bean&gt;

</pre><p>
      Now that we have our MySQL data source configured and ready to go,
      we write some Java code to access it. The example below will
      retrieve three random cities and their corresponding country using
      the data source we configured with Spring.
    </p><pre class="programlisting">
// Create a new application context. this processes the Spring config
ApplicationContext ctx =
    new ClassPathXmlApplicationContext("ex1appContext.xml");
// Retrieve the data source from the application context
    DataSource ds = (DataSource) ctx.getBean("dataSource");
// Open a database connection using Spring's DataSourceUtils
Connection c = DataSourceUtils.getConnection(ds);
try {
    // retrieve a list of three random cities
    PreparedStatement ps = c.prepareStatement(
        "select City.Name as 'City', Country.Name as 'Country' " +
        "from City inner join Country on City.CountryCode = Country.Code " +
        "order by rand() limit 3");
    ResultSet rs = ps.executeQuery();
    while(rs.next()) {
        String city = rs.getString("City");
        String country = rs.getString("Country");
        System.out.printf("The city %s is in %s%n", city, country);
    }
} catch (SQLException ex) {
    // something has failed and we print a stack trace to analyse the error
    ex.printStackTrace();
    // ignore failure closing connection
    try { c.close(); } catch (SQLException e) { }
} finally {
    // properly release our connection
    DataSourceUtils.releaseConnection(c, ds);
}
</pre><p>
      This is very similar to normal JDBC access to MySQL with the main
      difference being that we are using DataSourceUtils instead of the
      DriverManager to create the connection.
    </p><p>
      While it may seem like a small difference, the implications are
      somewhat far reaching. Spring manages this resource in a way
      similar to a container managed data source in a J2EE application
      server. When a connection is opened, it can be subsequently
      accessed in other parts of the code if it is synchronized with a
      transaction. This makes it possible to treat different parts of
      your application as transactional instead of passing around a
      database connection.
    </p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-spring-config-jdbctemplate"></a>12.1 Using <code class="classname">JdbcTemplate</code></h2></div></div></div><p>
        Spring makes extensive use of the Template method design pattern
        (see
        <a class="ulink" href="http://en.wikipedia.org/wiki/Template_method_pattern" target="_top">Template
        Method Pattern</a>). Our immediate focus will be on the
        <code class="literal">JdbcTemplate</code> and related classes,
        specifically <code class="literal">NamedParameterJdbcTemplate</code>. The
        template classes handle obtaining and releasing a connection for
        data access when one is needed.
      </p><p>
        The next example shows how to use
        <code class="literal">NamedParameterJdbcTemplate</code> inside of a DAO
        (Data Access Object) class to retrieve a random city given a
        country code.
      </p><pre class="programlisting">
public class Ex2JdbcDao {
     /**
     * Data source reference which will be provided by Spring.
     */
     private DataSource dataSource;

     /**
     * Our query to find a random city given a country code. Notice
     * the ":country" parameter toward the end. This is called a
     * named parameter.
     */
     private String queryString = "select Name from City " +
        "where CountryCode = :country order by rand() limit 1";

     /**
     * Retrieve a random city using Spring JDBC access classes.
     */
     public String getRandomCityByCountryCode(String cntryCode) {
         // A template that permits using queries with named parameters
         NamedParameterJdbcTemplate template =
         new NamedParameterJdbcTemplate(dataSource);
         // A java.util.Map is used to provide values for the parameters
         Map params = new HashMap();
         params.put("country", cntryCode);
         // We query for an Object and specify what class we are expecting
         return (String)template.queryForObject(queryString, params, String.class);
     }

    /**
    * A JavaBean setter-style method to allow Spring to inject the data source.
    * @param dataSource
    */
    public void setDataSource(DataSource dataSource) {
        this.dataSource = dataSource;
    }
}
</pre><p>
        The focus in the above code is on the
        <code class="function">getRandomCityByCountryCode()</code> method. We
        pass a country code and use the
        <code class="literal">NamedParameterJdbcTemplate</code> to query for a
        city. The country code is placed in a Map with the key
        "country", which is the parameter is named in the SQL query.
      </p><p>
        To access this code, you need to configure it with Spring by
        providing a reference to the data source.
      </p><pre class="programlisting">

&lt;bean id="dao" class="code.Ex2JdbcDao"&gt;
    &lt;property name="dataSource" ref="dataSource"/&gt;
&lt;/bean&gt;

</pre><p>
        At this point, we can just grab a reference to the DAO from
        Spring and call
        <code class="function">getRandomCityByCountryCode()</code>.
      </p><pre class="programlisting">
    // Create the application context
    ApplicationContext ctx =
    new ClassPathXmlApplicationContext("ex2appContext.xml");
    // Obtain a reference to our DAO
    Ex2JdbcDao dao = (Ex2JdbcDao) ctx.getBean("dao");

    String countryCode = "USA";

    // Find a few random cities in the US
    for(int i = 0; i &lt; 4; ++i)
        System.out.printf("A random city in %s is %s%n", countryCode,
            dao.getRandomCityByCountryCode(countryCode));
</pre><p>
        This example shows how to use Spring's JDBC classes to
        completely abstract away the use of traditional JDBC classes
        including <code class="literal">Connection</code> and
        <code class="literal">PreparedStatement</code>.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-spring-config-transactional"></a>12.2 Transactional JDBC Access</h2></div></div></div><p>
        You might be wondering how we can add transactions into our code
        if we do not deal directly with the JDBC classes. Spring
        provides a transaction management package that not only replaces
        JDBC transaction management, but also enables declarative
        transaction management (configuration instead of code).
      </p><p>
        To use transactional database access, we will need to change the
        storage engine of the tables in the world database. The
        downloaded script explicitly creates MyISAM tables which do not
        support transactional semantics. The InnoDB storage engine does
        support transactions and this is what we will be using. We can
        change the storage engine with the following statements.
      </p><pre class="programlisting">
ALTER TABLE City ENGINE=InnoDB;
ALTER TABLE Country ENGINE=InnoDB;
ALTER TABLE CountryLanguage ENGINE=InnoDB;
</pre><p>
        A good programming practice emphasized by Spring is separating
        interfaces and implementations. What this means is that we can
        create a Java interface and only use the operations on this
        interface without any internal knowledge of what the actual
        implementation is. We will let Spring manage the implementation
        and with this it will manage the transactions for our
        implementation.
      </p><p>
        First you create a simple interface:
      </p><pre class="programlisting">
public interface Ex3Dao {
    Integer createCity(String name, String countryCode,
    String district, Integer population);
}
</pre><p>
        This interface contains one method that will create a new city
        record in the database and return the id of the new record. Next
        you need to create an implementation of this interface.
      </p><pre class="programlisting">
public class Ex3DaoImpl implements Ex3Dao {
    protected DataSource dataSource;
    protected SqlUpdate updateQuery;
    protected SqlFunction idQuery;

    public Integer createCity(String name, String countryCode,
        String district, Integer population) {
            updateQuery.update(new Object[] { name, countryCode,
                   district, population });
            return getLastId();
        }

    protected Integer getLastId() {
        return idQuery.run();
    }
}
</pre><p>
        You can see that we only operate on abstract query objects here
        and do not deal directly with the JDBC API. Also, this is the
        complete implementation. All of our transaction management will
        be dealt with in the configuration. To get the configuration
        started, we need to create the DAO.
      </p><pre class="programlisting">

&lt;bean id="dao" class="code.Ex3DaoImpl"&gt;
    &lt;property name="dataSource" ref="dataSource"/&gt;
    &lt;property name="updateQuery"&gt;...&lt;/property&gt;
    &lt;property name="idQuery"&gt;...&lt;/property&gt;
&lt;/bean&gt;

</pre><p>
        Now you need to set up the transaction configuration. The first
        thing you must do is create transaction manager to manage the
        data source and a specification of what transaction properties
        are required for the <code class="literal">dao</code> methods.
      </p><pre class="programlisting">

&lt;bean id="transactionManager"
  class="org.springframework.jdbc.datasource.DataSourceTransactionManager"&gt;
    &lt;property name="dataSource" ref="dataSource"/&gt;
&lt;/bean&gt;

&lt;tx:advice id="txAdvice" transaction-manager="transactionManager"&gt;
    &lt;tx:attributes&gt;
        &lt;tx:method name="*"/&gt;
    &lt;/tx:attributes&gt;
&lt;/tx:advice&gt;

</pre><p>
        The preceding code creates a transaction manager that handles
        transactions for the data source provided to it. The
        <code class="literal">txAdvice</code> uses this transaction manager and
        the attributes specify to create a transaction for all methods.
        Finally you need to apply this advice with an AOP pointcut.
      </p><pre class="programlisting">

&lt;aop:config&gt;
    &lt;aop:pointcut id="daoMethods"
        expression="execution(* code.Ex3Dao.*(..))"/&gt;
     &lt;aop:advisor advice-ref="txAdvice" pointcut-ref="daoMethods"/&gt;
&lt;/aop:config&gt;

</pre><p>
        This basically says that all methods called on the
        <code class="literal">Ex3Dao</code> interface will be wrapped in a
        transaction. To make use of this, you only have to retrieve the
        <code class="literal">dao</code> from the application context and call a
        method on the <code class="literal">dao</code> instance.
      </p><pre class="programlisting">
Ex3Dao dao = (Ex3Dao) ctx.getBean("dao");
Integer id = dao.createCity(name,  countryCode, district, pop);
</pre><p>
        We can verify from this that there is no transaction management
        happening in our Java code and it is all configured with Spring.
        This is a very powerful notion and regarded as one of the most
        beneficial features of Spring.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-spring-config-connpooling"></a>12.3 Connection Pooling with Spring</h2></div></div></div><a class="indexterm" name="idm140410757175408"></a><p>
        In many situations, such as web applications, there will be a
        large number of small database transactions. When this is the
        case, it usually makes sense to create a pool of database
        connections available for web requests as needed. Although MySQL
        does not spawn an extra process when a connection is made, there
        is still a small amount of overhead to create and set up the
        connection. Pooling of connections also alleviates problems such
        as collecting large amounts of sockets in the
        <code class="literal">TIME_WAIT</code> state.
      </p><p>
        Setting up pooling of MySQL connections with Spring is as simple
        as changing the data source configuration in the application
        context. There are a number of configurations that we can use.
        The first example is based on the
        <a class="ulink" href="http://jakarta.apache.org/commons/dbcp/" target="_top">Jakarta
        Commons DBCP library</a>. The example below replaces the
        source configuration that was based on
        <code class="literal">DriverManagerDataSource</code> with DBCP's
        BasicDataSource.
      </p><pre class="programlisting">

&lt;bean id="dataSource" destroy-method="close"
  class="org.apache.commons.dbcp.BasicDataSource"&gt;
    &lt;property name="driverClassName" value="${db.driver}"/&gt;
    &lt;property name="url" value="${db.jdbcurl}"/&gt;
    &lt;property name="username" value="${db.username}"/&gt;
    &lt;property name="password" value="${db.password}"/&gt;
    &lt;property name="initialSize" value="3"/&gt;
&lt;/bean&gt;

</pre><p>
        The configuration of the two solutions is very similar. The
        difference is that DBCP will pool connections to the database
        instead of creating a new connection every time one is
        requested. We have also set a parameter here called
        <code class="literal">initialSize</code>. This tells DBCP that we want
        three connections in the pool when it is created.
      </p><p>
        Another way to configure connection pooling is to configure a
        data source in our J2EE application server. Using JBoss as an
        example, you can set up the MySQL connection pool by creating a
        file called <code class="filename">mysql-local-ds.xml</code> and placing
        it in the server/default/deploy directory in JBoss. Once we have
        this setup, we can use JNDI to look it up. With Spring, this
        lookup is very simple. The data source configuration looks like
        this.
      </p><pre class="programlisting">

&lt;jee:jndi-lookup id="dataSource" jndi-name="java:MySQL_DS"/&gt;

</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-glassfish-config"></a>Chapter 13 Using Connector/J with GlassFish</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-jsp">13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-servlet">13.2 A Simple Servlet with GlassFish, Connector/J and MySQL</a></span></dt></dl></div><a class="indexterm" name="idm140410757164832"></a><a class="indexterm" name="idm140410757163824"></a><p>
      This section explains how to use MySQL Connector/J with GlassFish ™
      Server Open Source Edition 3.0.1. GlassFish can be downloaded from
      the
      <a class="ulink" href="https://glassfish.dev.java.net/public/downloadsindex.html#top" target="_top">GlassFish
      website</a>.
    </p><p>
      Once GlassFish is installed, make sure it can access MySQL Connector/J. To do
      this, copy the MySQL Connector/J <code class="filename">jar</code> file to the
      <code class="filename"><em class="replaceable"><code>domain-dir</code></em>/lib</code>
      directory. For example, copy
      <code class="filename">mysql-connector-java-5.1.30-bin.jar</code> to
      <code class="filename">C:\<em class="replaceable"><code>glassfish-install-path</code></em>\domains\<em class="replaceable"><code>domain-name</code></em>\lib</code>.
      Restart the GlassFish Application Server. For more information,
      see <span class="quote">“<span class="quote">Integrating the JDBC Driver</span>”</span> in
      <em class="citetitle">GlassFish Server Open Source Edition Administration
      Guide</em>, available at
      <a class="ulink" href="https://glassfish.java.net/documentation.html" target="_top">GlassFish
      Server Documentation</a>.
    </p><p>
      You are now ready to create JDBC Connection Pools and JDBC
      Resources.
    </p><p>
      <span class="bold"><strong>Creating a Connection Pool</strong></span>
    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
          In the GlassFish Administration Console, using the navigation
          tree navigate to <span class="guilabel">Resources</span>,
          <span class="guilabel">JDBC</span>, <span class="guilabel">Connection
          Pools</span>.
        </p></li><li class="listitem"><p>
          In the <span class="guilabel">JDBC Connection Pools</span> frame click
          <span class="guibutton">New</span>. You will enter a two step wizard.
        </p></li><li class="listitem"><p>
          In the <span class="guilabel">Name</span> field under <span class="guilabel">General
          Settings</span> enter the name for the connection pool,
          for example enter <strong class="userinput"><code>MySQLConnPool</code></strong>.
        </p></li><li class="listitem"><p>
          In the <span class="guilabel">Resource Type</span> field, select
          <code class="literal">javax.sql.DataSource</code> from the drop-down
          listbox.
        </p></li><li class="listitem"><p>
          In the <span class="guilabel">Database Vendor</span> field, select
          <code class="literal">MySQL</code> from the drop-down listbox. Click
          <span class="guibutton">Next</span> to go to the next page of the
          wizard.
        </p></li><li class="listitem"><p>
          You can accept the default settings for General Settings, Pool
          Settings and Transactions for this example. Scroll down to
          Additional Properties.
        </p></li><li class="listitem"><p>
          In Additional Properties you will need to ensure the following
          properties are set:
        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <span class="bold"><strong>ServerName</strong></span> - The server
              to connect to. For local testing this will be
              <code class="literal">localhost</code>.
            </p></li><li class="listitem"><p>
              <span class="bold"><strong>User</strong></span> - The user name with
              which to connect to MySQL.
            </p></li><li class="listitem"><p>
              <span class="bold"><strong>Password</strong></span> - The
              corresponding password for the user.
            </p></li><li class="listitem"><p>
              <span class="bold"><strong>DatabaseName</strong></span> - The
              database to connect to, for example the sample MySQL
              database <code class="literal">World</code>.
            </p></li></ul></div></li><li class="listitem"><p>
          Click <span class="guibutton">Finish</span> to exit the wizard. You
          will be taken to the <span class="guilabel">JDBC Connection
          Pools</span> page where all current connection pools,
          including the one you just created, will be displayed.
        </p></li><li class="listitem"><p>
          In the <span class="guilabel">JDBC Connection Pools</span> frame click
          on the connection pool you just created. Here, you can review
          and edit information about the connection pool. Because
          Connector/J does not support optimized validation queries, go
          to the <span class="guilabel">Advanced</span> tab, and under Connection
          Validation, configure the following settings:

          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
                <span class="bold"><strong>Connection Validation</strong></span> -
                select <span class="guilabel">Required</span>.
              </p></li><li class="listitem"><p>
                <span class="bold"><strong>Validation Method</strong></span> -
                select <span class="guilabel">table</span> from the drop-down
                menu.
              </p></li><li class="listitem"><p>
                <span class="bold"><strong>Table Name</strong></span> - enter
                <code class="literal">DUAL</code>.
              </p></li></ul></div><p>
        </p></li><li class="listitem"><p>
          To test your connection pool click the
          <span class="guibutton">Ping</span> button at the top of the frame. A
          message will be displayed confirming correct operation or
          otherwise. If an error message is received recheck the
          previous steps, and ensure that MySQL Connector/J has been correctly copied
          into the previously specified location.
        </p></li></ol></div><p>
      Now that you have created a connection pool you will also need to
      create a JDBC Resource (data source) for use by your application.
    </p><p>
      <span class="bold"><strong>Creating a JDBC Resource</strong></span>
    </p><p>
      Your Java application will usually reference a data source object
      to establish a connection with the database. This needs to be
      created first using the following procedure.
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Using the navigation tree in the GlassFish Administration
          Console, navigate to <span class="guilabel">Resources</span>,
          <span class="guilabel">JDBC</span>, <span class="guilabel">JDBC
          Resources</span>. A list of resources will be displayed in
          the <span class="guilabel">JDBC Resources</span> frame.
        </p></li><li class="listitem"><p>
          Click <span class="guibutton">New</span>. The <span class="guilabel">New JDBC
          Resource</span> frame will be displayed.
        </p></li><li class="listitem"><p>
          In the <span class="guilabel">JNDI Name</span> field, enter the JNDI
          name that will be used to access this resource, for example
          enter <strong class="userinput"><code>jdbc/MySQLDataSource</code></strong>.
        </p></li><li class="listitem"><p>
          In the <span class="guilabel">Pool Name</span> field, select a
          connection pool you want this resource to use from the
          drop-down listbox.
        </p></li><li class="listitem"><p>
          Optionally, you can enter a description into the
          <span class="guilabel">Description</span> field.
        </p></li><li class="listitem"><p>
          Additional properties can be added if required.
        </p></li><li class="listitem"><p>
          Click <span class="guibutton">OK</span> to create the new JDBC
          resource. The <span class="guilabel">JDBC Resources</span> frame will
          list all available JDBC Resources.
        </p></li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-glassfish-config-jsp"></a>13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL</h2></div></div></div><p>
        This section shows how to deploy a simple JSP application on
        GlassFish, that connects to a MySQL database.
      </p><p>
        This example assumes you have already set up a suitable
        Connection Pool and JDBC Resource, as explained in the preceding
        sections. It is also assumed you have a sample database
        installed, such as <code class="literal">world</code>.
      </p><p>
        The main application code, <code class="filename">index.jsp</code> is
        presented here:
      </p><pre class="programlisting">

&lt;%@ page import="java.sql.*, javax.sql.*, java.io.*, javax.naming.*" %&gt;
&lt;html&gt;
&lt;head&gt;&lt;title&gt;Hello world from JSP&lt;/title&gt;&lt;/head&gt;
&lt;body&gt;
&lt;%
  InitialContext ctx;
  DataSource ds;
  Connection conn;
  Statement stmt;
  ResultSet rs;

  try {
    ctx = new InitialContext();
    ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource");
    //ds = (DataSource) ctx.lookup("jdbc/MySQLDataSource");
    conn = ds.getConnection();
    stmt = conn.createStatement();
    rs = stmt.executeQuery("SELECT * FROM Country");

    while(rs.next()) {
%&gt;
    &lt;h3&gt;Name: &lt;%= rs.getString("Name") %&gt;&lt;/h3&gt;
    &lt;h3&gt;Population: &lt;%= rs.getString("Population") %&gt;&lt;/h3&gt;
&lt;%    
    }
  }
  catch (SQLException se) {
%&gt;
    &lt;%= se.getMessage() %&gt;
&lt;%      
  }
  catch (NamingException ne) {
%&gt;  
    &lt;%= ne.getMessage() %&gt;
&lt;%
  }
%&gt;
&lt;/body&gt;
&lt;/html&gt;

</pre><p>
        In addition two XML files are required:
        <code class="filename">web.xml</code>, and
        <code class="filename">sun-web.xml</code>. There may be other files
        present, such as classes and images. These files are organized
        into the directory structure as follows:
      </p><pre class="programlisting">
index.jsp
WEB-INF
   |
   - web.xml
   - sun-web.xml
</pre><p>
        The code for <code class="filename">web.xml</code> is:
      </p><pre class="programlisting">

&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"&gt;
  &lt;display-name&gt;HelloWebApp&lt;/display-name&gt;  
  &lt;distributable/&gt;
  &lt;resource-ref&gt;
    &lt;res-ref-name&gt;jdbc/MySQLDataSource&lt;/res-ref-name&gt;
    &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
    &lt;res-auth&gt;Container&lt;/res-auth&gt;
    &lt;res-sharing-scope&gt;Shareable&lt;/res-sharing-scope&gt;                
  &lt;/resource-ref&gt;
&lt;/web-app&gt;

</pre><p>
        The code for <code class="filename">sun-web.xml</code> is:
      </p><pre class="programlisting">

&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 8.1 Servlet 2.4//EN" "http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd"&gt;
&lt;sun-web-app&gt;
  &lt;context-root&gt;HelloWebApp&lt;/context-root&gt;
  &lt;resource-ref&gt;
    &lt;res-ref-name&gt;jdbc/MySQLDataSource&lt;/res-ref-name&gt;
    &lt;jndi-name&gt;jdbc/MySQLDataSource&lt;/jndi-name&gt;  
  &lt;/resource-ref&gt; 
&lt;/sun-web-app&gt;

</pre><p>
        These XML files illustrate a very important aspect of running
        JDBC applications on GlassFish. On GlassFish it is important to
        map the string specified for a JDBC resource to its JNDI name,
        as set up in the GlassFish administration console. In this
        example, the JNDI name for the JDBC resource, as specified in
        the GlassFish Administration console when creating the JDBC
        Resource, was <code class="literal">jdbc/MySQLDataSource</code>. This must
        be mapped to the name given in the application. In this example
        the name specified in the application,
        <code class="literal">jdbc/MySQLDataSource</code>, and the JNDI name,
        happen to be the same, but this does not necessarily have to be
        the case. Note that the XML element &lt;res-ref-name&gt; is used
        to specify the name as used in the application source code, and
        this is mapped to the JNDI name specified using the
        &lt;jndi-name&gt; element, in the file
        <code class="filename">sun-web.xml</code>. The resource also has to be
        created in the <code class="filename">web.xml</code> file, although the
        mapping of the resource to a JNDI name takes place in the
        <code class="filename">sun-web.xml</code> file.
      </p><p>
        If you do not have this mapping set up correctly in the XML
        files you will not be able to lookup the data source using a
        JNDI lookup string such as:
      </p><pre class="programlisting">
ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource");
</pre><p>
        You will still be able to access the data source directly using:
      </p><pre class="programlisting">
ds = (DataSource) ctx.lookup("jdbc/MySQLDataSource");
</pre><p>
        With the source files in place, in the correct directory
        structure, you are ready to deploy the application:
      </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
            In the navigation tree, navigate to
            <span class="guilabel">Applications</span> - the
            <span class="guilabel">Applications</span> frame will be displayed.
            Click <span class="guibutton">Deploy</span>.
          </p></li><li class="listitem"><p>
            You can now deploy an application packaged into a single WAR
            file from a remote client, or you can choose a packaged file
            or directory that is locally accessible to the server. If
            you are simply testing an application locally you can simply
            point GlassFish at the directory that contains your
            application, without needing to package the application into
            a WAR file.
          </p></li><li class="listitem"><p>
            Now select the application type from the
            <span class="guilabel">Type</span> drop-down listbox, which in this
            example is <code class="literal">Web application</code>.
          </p></li><li class="listitem"><p>
            Click OK.
          </p></li></ol></div><p>
        Now, when you navigate to the <span class="guilabel">Applications</span>
        frame, you will have the option to <span class="guilabel">Launch</span>,
        <span class="guilabel">Redeploy</span>, or <span class="guilabel">Restart</span>
        your application. You can test your application by clicking
        <span class="guilabel">Launch</span>. The application will connection to
        the MySQL database and display the Name and Population of
        countries in the <code class="literal">Country</code> table.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-glassfish-config-servlet"></a>13.2 A Simple Servlet with GlassFish, Connector/J and MySQL</h2></div></div></div><a class="indexterm" name="idm140410757062288"></a><p>
        This section describes a simple servlet that can be used in the
        GlassFish environment to access a MySQL database. As with the
        previous section, this example assumes the sample database
        <code class="literal">world</code> is installed.
      </p><p>
        The project is set up with the following directory structure:
      </p><pre class="programlisting">
index.html
WEB-INF
   |
   - web.xml
   - sun-web.xml
   - classes
        |
        - HelloWebServlet.java
        - HelloWebServlet.class
</pre><p>
        The code for the servlet, located in
        <code class="filename">HelloWebServlet.java</code>, is as follows:
      </p><pre class="programlisting">

import javax.servlet.http.*;
import javax.servlet.*;
import java.io.*;
import java.sql.*;
import javax.sql.*;
import javax.naming.*;

public class HelloWebServlet extends HttpServlet {

  InitialContext ctx = null;
  DataSource ds = null;
  Connection conn = null;
  PreparedStatement ps = null;
  ResultSet rs = null;

  String sql = "SELECT Name, Population FROM Country WHERE Name=?";

  public void init () throws ServletException {
    try {
      ctx = new InitialContext();
      ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource");
      conn = ds.getConnection();
      ps = conn.prepareStatement(sql);
    }
    catch (SQLException se) {
      System.out.println("SQLException: "+se.getMessage());
    }
    catch (NamingException ne) {
      System.out.println("NamingException: "+ne.getMessage());  
    }  
  }

  public void destroy () {
    try {
      if (rs != null)
        rs.close();
      if (ps != null)
        ps.close();
      if (conn != null)
        conn.close();
      if (ctx != null)
        ctx.close(); 
    }     
    catch (SQLException se) {
      System.out.println("SQLException: "+se.getMessage());
    }
    catch (NamingException ne) {
      System.out.println("NamingException: "+ne.getMessage());  
    }  
  }

  public void doPost(HttpServletRequest req, HttpServletResponse resp){
    try {
      String country_name = req.getParameter("country_name");    
      resp.setContentType("text/html");
      PrintWriter writer = resp.getWriter();
      writer.println("&lt;html&gt;&lt;body&gt;");
      writer.println("&lt;p&gt;Country: "+country_name+"&lt;/p&gt;");
      ps.setString(1, country_name);
      rs = ps.executeQuery();
      if (!rs.next()){
        writer.println("&lt;p&gt;Country does not exist!&lt;/p&gt;");
      }
      else {
        rs.beforeFirst();
        while(rs.next()) {
          writer.println("&lt;p&gt;Name: "+rs.getString("Name")+"&lt;/p&gt;");
          writer.println("&lt;p&gt;Population: "+rs.getString("Population")+"&lt;/p&gt;");
        }
      }
      writer.println("&lt;/body&gt;&lt;/html&gt;");
      writer.close(); 
    }
    catch (Exception e) {
      e.printStackTrace();
    }  
  }

  public void doGet(HttpServletRequest req, HttpServletResponse resp){
    try {    
      resp.setContentType("text/html");
      PrintWriter writer = resp.getWriter();
      writer.println("&lt;html&gt;&lt;body&gt;");
      writer.println("&lt;p&gt;Hello from servlet doGet()&lt;/p&gt;");
      writer.println("&lt;/body&gt;&lt;/html&gt;");
      writer.close(); 
    }
    catch (Exception e) {
      e.printStackTrace();
    }  
  }
}

</pre><p>
        In the preceding code a basic <code class="literal">doGet()</code> method
        is implemented, but is not used in the example. The code to
        establish the connection with the database is as shown in the
        previous example,
        <a class="xref" href="#connector-j-usagenotes-glassfish-config-jsp" title="13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL">Section 13.1, “A Simple JSP Application with GlassFish, Connector/J and MySQL”</a>,
        and is most conveniently located in the servlet
        <code class="literal">init()</code> method. The corresponding freeing of
        resources is located in the destroy method. The main
        functionality of the servlet is located in the
        <code class="literal">doPost()</code> method. If the user enters into the
        input form a country name that can be located in the database,
        the population of the country is returned. The code is invoked
        using a POST action associated with the input form. The form is
        defined in the file <code class="filename">index.html</code>:
      </p><pre class="programlisting">

&lt;html&gt;
  &lt;head&gt;&lt;title&gt;HelloWebServlet&lt;/title&gt;&lt;/head&gt;
  
  &lt;body&gt;
    &lt;h1&gt;HelloWebServlet&lt;/h1&gt;
    
    &lt;p&gt;Please enter country name:&lt;/p&gt;
    
    &lt;form action="HelloWebServlet" method="POST"&gt;
      &lt;input type="text" name="country_name" length="50" /&gt;
      &lt;input type="submit" value="Submit" /&gt;
    &lt;/form&gt;
    
  &lt;/body&gt;
&lt;/html&gt;

</pre><p>
        The XML files <code class="filename">web.xml</code> and
        <code class="filename">sun-web.xml</code> are as for the example in the
        preceding section,
        <a class="xref" href="#connector-j-usagenotes-glassfish-config-jsp" title="13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL">Section 13.1, “A Simple JSP Application with GlassFish, Connector/J and MySQL”</a>,
        no additional changes are required.
      </p><p>
        When compiling the Java source code, you will need to specify
        the path to the file <code class="filename">javaee.jar</code>. On
        Windows, this can be done as follows:
      </p><pre class="programlisting">
shell&gt; javac -classpath c:\glassfishv3\glassfish\lib\javaee.jar HelloWebServlet.java 
</pre><p>
        Once the code is correctly located within its directory
        structure, and compiled, the application can be deployed in
        GlassFish. This is done in exactly the same way as described in
        the preceding section,
        <a class="xref" href="#connector-j-usagenotes-glassfish-config-jsp" title="13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL">Section 13.1, “A Simple JSP Application with GlassFish, Connector/J and MySQL”</a>.
      </p><p>
        Once deployed the application can be launched from within the
        GlassFish Administration Console. Enter a country name such as
        <span class="quote">“<span class="quote">England</span>”</span>, and the application will return
        <span class="quote">“<span class="quote">Country does not exist!</span>”</span>. Enter
        <span class="quote">“<span class="quote">France</span>”</span>, and the application will return a
        population of 59225700.
      </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-fabric"></a>Chapter 14 Using Connector/J with MySQL Fabric</h1></div></div></div><a class="indexterm" name="idm140410757037824"></a><p>
      MySQL Fabric is a system for managing a farm of MySQL servers (and
      other components). Fabric provides an extensible and easy to use
      system for managing a MySQL deployment for sharding and
      high-availability.
    </p><p>
      For more information on MySQL Fabric, see
      <a class="ulink" href="http://dev.mysql.com/doc/mysql-utilities/1.5/en/fabric.html" target="_top">MySQL Fabric</a>. For instructions on how to use
      Connector/J with MySQL Fabric, see
      <a class="ulink" href="http://dev.mysql.com/doc/mysql-utilities/1.5/en/connector-j-fabric.html" target="_top">Using Connector/J with MySQL Fabric</a>.
    </p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-troubleshooting"></a>Chapter 15 Troubleshooting Connector/J Applications</h1></div></div></div><a class="indexterm" name="idm140410757032768"></a><a class="indexterm" name="idm140410757031280"></a><a class="indexterm" name="idm140410757029792"></a><p>
      This section explains the symptoms and resolutions for the most
      commonly encountered issues with applications using MySQL
      Connector/J.
    </p><p><span class="bold"><strong>Questions</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="link" href="#qandaitem-15-1-1">15.1: </a>
            When I try to connect to the database with MySQL
            Connector/J, I get the following exception:
          </p><pre class="programlisting">
SQLException: Server configuration denies access to data source
SQLState: 08001
VendorError: 0
</pre><p>
            What is going on? I can connect just fine with the MySQL
            command-line client.
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-2">15.2: </a>
            My application throws an SQLException 'No Suitable Driver'.
            Why is this happening?
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-3">15.3: </a>
            I'm trying to use MySQL Connector/J in an applet or
            application and I get an exception similar to:
          </p><pre class="programlisting">
SQLException: Cannot connect to MySQL server on host:3306.
Is there a MySQL server running on the machine/port you
are trying to connect to?

(java.security.AccessControlException)
SQLState: 08S01
VendorError: 0 
</pre></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-4">15.4: </a>
            I have a servlet/application that works fine for a day, and
            then stops working overnight
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-5">15.5: </a>
            I'm trying to use JDBC 2.0 updatable result sets, and I get
            an exception saying my result set is not updatable.
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-6">15.6: </a>
            I cannot connect to the MySQL server using Connector/J, and
            I'm sure the connection parameters are correct.
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-7">15.7: </a>
            I am trying to connect to my MySQL server within my
            application, but I get the following error and stack trace:
          </p><pre class="programlisting">
java.net.SocketException
MESSAGE: Software caused connection abort: recv failed

STACKTRACE:

java.net.SocketException: Software caused connection abort: recv failed
at java.net.SocketInputStream.socketRead0(Native Method)
at java.net.SocketInputStream.read(Unknown Source)
at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1392)
at com.mysql.jdbc.MysqlIO.readPacket(MysqlIO.java:1414)
at com.mysql.jdbc.MysqlIO.doHandshake(MysqlIO.java:625)
at com.mysql.jdbc.Connection.createNewIO(Connection.java:1926)
at com.mysql.jdbc.Connection.&lt;init&gt;(Connection.java:452)
at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:411)
</pre></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-8">15.8: </a>
            My application is deployed through JBoss and I am using
            transactions to handle the statements on the MySQL database.
            Under heavy loads, I am getting an error and stack trace,
            but these only occur after a fixed period of heavy activity.
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-9">15.9: </a>
            When using <span class="command"><strong>gcj</strong></span>, a
            <code class="literal">java.io.CharConversionException</code> exception
            is raised when working with certain character sequences.
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-10">15.10: </a>
            Updating a table that contains a
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_primary_key" target="_top">primary key</a> that is
            either <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a> or compound
            primary key that uses <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>
            fails to update the table and raises an exception.
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-11">15.11: </a>
            You get an
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/error-messages-server.html#error_er_net_packet_too_large" target="_top"><code class="literal">ER_NET_PACKET_TOO_LARGE</code></a>
            exception, even though the binary blob size you want to
            insert using JDBC is safely below the
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html#sysvar_max_allowed_packet" target="_top"><code class="literal">max_allowed_packet</code></a> size.
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-12">15.12: </a>
            What should you do if you receive error messages similar to
            the following: <span class="quote">“<span class="quote">Communications link failure – Last
            packet sent to the server was X ms ago</span>”</span>?
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-13">15.13: </a>
            Why does Connector/J not reconnect to MySQL and re-issue the
            statement after a communication failure, instead of throwing
            an Exception, even though I use the
            <code class="literal">autoReconnect</code> connection string option?
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-14">15.14: </a>
            How can I use 3-byte UTF8 with Connector/J?
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-15">15.15: </a>
            How can I use 4-byte UTF8, <code class="literal">utf8mb4</code> with
            Connector/J?
          </p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-16">15.16: </a>
            Using <code class="literal">useServerPrepStmts=false</code> and
            certain character encodings can lead to corruption when
            inserting BLOBs. How can this be avoided?
          </p></li></ul></div><p><span class="bold"><strong>Questions and Answers</strong></span></p><p><a name="qandaitem-15-1-1"></a><span class="bold"><strong>15.1: </strong></span><span class="bold"><strong>
            When I try to connect to the database with MySQL
            Connector/J, I get the following exception:
          </strong></span></p><pre class="programlisting">
SQLException: Server configuration denies access to data source
SQLState: 08001
VendorError: 0
</pre><p><span class="bold"><strong>
            What is going on? I can connect just fine with the MySQL
            command-line client.
          </strong></span></p><p>
            MySQL Connector/J must use TCP/IP sockets to connect to
            MySQL, as Java does not support Unix Domain Sockets.
            Therefore, when MySQL Connector/J connects to MySQL, the
            security manager in MySQL server will use its grant tables
            to determine whether the connection is permitted.
          </p><p>
            You must add the necessary security credentials to the MySQL
            server for this to happen, using the
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/grant.html" target="_top"><code class="literal">GRANT</code></a> statement to your MySQL
            Server. See <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/grant.html" target="_top">GRANT Syntax</a>, for more information.
          </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
              Testing your connectivity with the
              <span class="command"><strong>mysql</strong></span> command-line client will not work
              unless you add the "host" flag, and use something other
              than <code class="literal">localhost</code> for the host. The
              <span class="command"><strong>mysql</strong></span> command-line client will use Unix
              domain sockets if you use the special host name
              <code class="literal">localhost</code>. If you are testing
              connectivity to <code class="literal">localhost</code>, use
              <code class="literal">127.0.0.1</code> as the host name instead.
            </p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Warning</div><p>
              Changing privileges and permissions improperly in MySQL
              can potentially cause your server installation to not have
              optimal security properties.
            </p></div><p><a name="qandaitem-15-1-2"></a><span class="bold"><strong>15.2: </strong></span><span class="bold"><strong>
            My application throws an SQLException 'No Suitable Driver'.
            Why is this happening?
          </strong></span></p><p>
            There are three possible causes for this error:
          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
                The Connector/J driver is not in your
                <code class="literal">CLASSPATH</code>, see
                <a class="xref" href="#connector-j-installing" title="Chapter 3 Connector/J Installation">Chapter 3, <i>Connector/J Installation</i></a>.
              </p></li><li class="listitem"><p>
                The format of your connection URL is incorrect, or you
                are referencing the wrong JDBC driver.
              </p></li><li class="listitem"><p>
                When using DriverManager, the
                <code class="literal">jdbc.drivers</code> system property has not
                been populated with the location of the Connector/J
                driver.
              </p></li></ul></div><p><a name="qandaitem-15-1-3"></a><span class="bold"><strong>15.3: </strong></span><span class="bold"><strong>
            I'm trying to use MySQL Connector/J in an applet or
            application and I get an exception similar to:
          </strong></span></p><pre class="programlisting">
SQLException: Cannot connect to MySQL server on host:3306.
Is there a MySQL server running on the machine/port you
are trying to connect to?

(java.security.AccessControlException)
SQLState: 08S01
VendorError: 0 
</pre><p>
            Either you're running an Applet, your MySQL server has been
            installed with the "skip-networking" option set, or your
            MySQL server has a firewall sitting in front of it.
          </p><p>
            Applets can only make network connections back to the
            machine that runs the web server that served the .class
            files for the applet. This means that MySQL must run on the
            same machine (or you must have some sort of port
            re-direction) for this to work. This also means that you
            will not be able to test applets from your local file
            system, you must always deploy them to a web server.
          </p><p>
            MySQL Connector/J can only communicate with MySQL using
            TCP/IP, as Java does not support Unix domain sockets. TCP/IP
            communication with MySQL might be affected if MySQL was
            started with the "skip-networking" flag, or if it is
            firewalled.
          </p><p>
            If MySQL has been started with the "skip-networking" option
            set (the Debian Linux package of MySQL server does this for
            example), you need to comment it out in the file
            <code class="filename">/etc/mysql/my.cnf</code> or
            <code class="filename">/etc/my.cnf</code>. Of course your
            <code class="filename">my.cnf</code> file might also exist in the
            <code class="filename">data</code> directory of your MySQL server, or
            anywhere else (depending on how MySQL was compiled for your
            system). Binaries created by us always look in
            <code class="filename">/etc/my.cnf</code> and
            <code class="filename"><em class="replaceable"><code>datadir</code></em>/my.cnf</code>.
            If your MySQL server has been firewalled, you will need to
            have the firewall configured to allow TCP/IP connections
            from the host where your Java code is running to the MySQL
            server on the port that MySQL is listening to (by default,
            3306).
          </p><p><a name="qandaitem-15-1-4"></a><span class="bold"><strong>15.4: </strong></span><span class="bold"><strong>
            I have a servlet/application that works fine for a day, and
            then stops working overnight
          </strong></span></p><p>
            MySQL closes connections after 8 hours of inactivity. You
            either need to use a connection pool that handles stale
            connections or use the <code class="option">autoReconnect</code>
            parameter (see
            <a class="xref" href="#connector-j-reference-configuration-properties" title="5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
        for Connector/J”</a>).
          </p><p>
            Also, catch <code class="literal">SQLExceptions</code> in your
            application and deal with them, rather than propagating them
            all the way until your application exits. This is just good
            programming practice. MySQL Connector/J will set the
            <code class="literal">SQLState</code> (see
            <code class="literal">java.sql.SQLException.getSQLState()</code> in
            your API docs) to <code class="literal">08S01</code> when it
            encounters network-connectivity issues during the processing
            of a query. Attempt to reconnect to MySQL at this point.
          </p><p>
            The following (simplistic) example shows what code that can
            handle these exceptions might look like:
          </p><p>
            </p><div class="example"><a name="connector-j-examples-transaction-retry"></a><p class="title"><b>Example 15.1 Connector/J: Example of transaction with retry logic</b></p><div class="example-contents"><pre class="programlisting">
public void doBusinessOp() throws SQLException {
    Connection conn = null;
    Statement stmt = null;
    ResultSet rs = null;

    //
    // How many times do you want to retry the transaction
    // (or at least _getting_ a connection)?
    //
    int retryCount = 5;

    boolean transactionCompleted = false;

    do {
        try {
            conn = getConnection(); // assume getting this from a
                                    // javax.sql.DataSource, or the
                                    // java.sql.DriverManager

            conn.setAutoCommit(false);

            //
            // Okay, at this point, the 'retry-ability' of the
            // transaction really depends on your application logic,
            // whether or not you're using autocommit (in this case
            // not), and whether you're using transactional storage
            // engines
            //
            // For this example, we'll assume that it's _not_ safe
            // to retry the entire transaction, so we set retry
            // count to 0 at this point
            //
            // If you were using exclusively transaction-safe tables,
            // or your application could recover from a connection going
            // bad in the middle of an operation, then you would not
            // touch 'retryCount' here, and just let the loop repeat
            // until retryCount == 0.
            //
            retryCount = 0;

            stmt = conn.createStatement();

            String query = "SELECT foo FROM bar ORDER BY baz";

            rs = stmt.executeQuery(query);

            while (rs.next()) {
            }

            rs.close();
            rs = null;

            stmt.close();
            stmt = null;

            conn.commit();
            conn.close();
            conn = null;

            transactionCompleted = true;
        } catch (SQLException sqlEx) {

            //
            // The two SQL states that are 'retry-able' are 08S01
            // for a communications error, and 40001 for deadlock.
            //
            // Only retry if the error was due to a stale connection,
            // communications problem or deadlock
            //

            String sqlState = sqlEx.getSQLState();

            if ("08S01".equals(sqlState) || "40001".equals(sqlState)) {
                retryCount -= 1;
            } else {
                retryCount = 0;
            }
        } finally {
            if (rs != null) {
                try {
                    rs.close();
                } catch (SQLException sqlEx) {
                    // You'd probably want to log this...
                }
            }

            if (stmt != null) {
                try {
                    stmt.close();
                } catch (SQLException sqlEx) {
                    // You'd probably want to log this as well...
                }
            }

            if (conn != null) {
                try {
                    //
                    // If we got here, and conn is not null, the
                    // transaction should be rolled back, as not
                    // all work has been done

                    try {
                        conn.rollback();
                    } finally {
                        conn.close();
                    }
                } catch (SQLException sqlEx) {
                    //
                    // If we got an exception here, something
                    // pretty serious is going on, so we better
                    // pass it up the stack, rather than just
                    // logging it...

                    throw sqlEx;
                }
            }
        }
    } while (!transactionCompleted &amp;&amp; (retryCount &gt; 0));
}
</pre></div></div><p><br class="example-break">
          </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
              Use of the <code class="option">autoReconnect</code> option is not
              recommended because there is no safe method of
              reconnecting to the MySQL server without risking some
              corruption of the connection state or database state
              information. Instead, use a connection pool, which will
              enable your application to connect to the MySQL server
              using an available connection from the pool. The
              <code class="option">autoReconnect</code> facility is deprecated, and
              may be removed in a future release.
            </p></div><p><a name="qandaitem-15-1-5"></a><span class="bold"><strong>15.5: </strong></span><span class="bold"><strong>
            I'm trying to use JDBC 2.0 updatable result sets, and I get
            an exception saying my result set is not updatable.
          </strong></span></p><p>
            Because MySQL does not have row identifiers, MySQL
            Connector/J can only update result sets that have come from
            queries on tables that have at least one
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_primary_key" target="_top">primary key</a>, the
            query must select every primary key column, and the query
            can only span one table (that is, no joins). This is
            outlined in the JDBC specification.
          </p><p>
            Note that this issue only occurs when using updatable result
            sets, and is caused because Connector/J is unable to
            guarantee that it can identify the correct rows within the
            result set to be updated without having a unique reference
            to each row. There is no requirement to have a unique field
            on a table if you are using
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/update.html" target="_top"><code class="literal">UPDATE</code></a> or
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/delete.html" target="_top"><code class="literal">DELETE</code></a> statements on a table
            where you can individually specify the criteria to be
            matched using a <code class="literal">WHERE</code> clause.
          </p><p><a name="qandaitem-15-1-6"></a><span class="bold"><strong>15.6: </strong></span><span class="bold"><strong>
            I cannot connect to the MySQL server using Connector/J, and
            I'm sure the connection parameters are correct.
          </strong></span></p><p>
            Make sure that the
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/server-options.html#option_mysqld_skip-networking" target="_top"><code class="option">skip-networking</code></a> option has
            not been enabled on your server. Connector/J must be able to
            communicate with your server over TCP/IP; named sockets are
            not supported. Also ensure that you are not filtering
            connections through a firewall or other network security
            system. For more information, see
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/can-not-connect-to-server.html" target="_top">Can't connect to [local] MySQL server</a>.
          </p><p><a name="qandaitem-15-1-7"></a><span class="bold"><strong>15.7: </strong></span><span class="bold"><strong>
            I am trying to connect to my MySQL server within my
            application, but I get the following error and stack trace:
          </strong></span></p><pre class="programlisting">
java.net.SocketException
MESSAGE: Software caused connection abort: recv failed

STACKTRACE:

java.net.SocketException: Software caused connection abort: recv failed
at java.net.SocketInputStream.socketRead0(Native Method)
at java.net.SocketInputStream.read(Unknown Source)
at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1392)
at com.mysql.jdbc.MysqlIO.readPacket(MysqlIO.java:1414)
at com.mysql.jdbc.MysqlIO.doHandshake(MysqlIO.java:625)
at com.mysql.jdbc.Connection.createNewIO(Connection.java:1926)
at com.mysql.jdbc.Connection.&lt;init&gt;(Connection.java:452)
at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:411)
</pre><p>
            The error probably indicates that you are using a older
            version of the Connector/J JDBC driver (2.0.14 or 3.0.x) and
            you are trying to connect to a MySQL server with version
            4.1x or newer. The older drivers are not compatible with 4.1
            or newer of MySQL as they do not support the newer
            authentication mechanisms.
          </p><p>
            It is likely that the older version of the Connector/J
            driver exists within your application directory or your
            <code class="literal">CLASSPATH</code> includes the older Connector/J
            package.
          </p><p><a name="qandaitem-15-1-8"></a><span class="bold"><strong>15.8: </strong></span><span class="bold"><strong>
            My application is deployed through JBoss and I am using
            transactions to handle the statements on the MySQL database.
            Under heavy loads, I am getting an error and stack trace,
            but these only occur after a fixed period of heavy activity.
          </strong></span></p><p>
            This is a JBoss, not Connector/J, issue and is connected to
            the use of transactions. Under heavy loads the time taken
            for transactions to complete can increase, and the error is
            caused because you have exceeded the predefined timeout.
          </p><p>
            You can increase the timeout value by setting the
            <code class="literal">TransactionTimeout</code> attribute to the
            <code class="literal">TransactionManagerService</code> within the
            <code class="filename">/conf/jboss-service.xml</code> file
            (pre-4.0.3) or <code class="filename">/deploy/jta-service.xml</code>
            for JBoss 4.0.3 or later. See
            <a class="ulink" href="http://wiki.jboss.org/wiki/Wiki.jsp?page=TransactionTimeout" target="_top">TransactionTimeout</a>
            within the JBoss wiki for more information.
          </p><p><a name="qandaitem-15-1-9"></a><span class="bold"><strong>15.9: </strong></span><span class="bold"><strong>
            When using <span class="command"><strong>gcj</strong></span>, a
            <code class="literal">java.io.CharConversionException</code> exception
            is raised when working with certain character sequences.
          </strong></span></p><p>
            This is a known issue with <span class="command"><strong>gcj</strong></span> which
            raises an exception when it reaches an unknown character or
            one it cannot convert. Add
            <code class="literal">useJvmCharsetConverters=true</code> to your
            connection string to force character conversion outside of
            the <span class="command"><strong>gcj</strong></span> libraries, or try a different
            JDK.
          </p><p><a name="qandaitem-15-1-10"></a><span class="bold"><strong>15.10: </strong></span><span class="bold"><strong>
            Updating a table that contains a
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_primary_key" target="_top">primary key</a> that is
            either <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a> or compound
            primary key that uses <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>
            fails to update the table and raises an exception.
          </strong></span></p><p>
            Connector/J adds conditions to the <code class="literal">WHERE</code>
            clause during an <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/update.html" target="_top"><code class="literal">UPDATE</code></a> to
            check the old values of the primary key. If there is no
            match, then Connector/J considers this a failure condition
            and raises an exception.
          </p><p>
            The problem is that rounding differences between supplied
            values and the values stored in the database may mean that
            the values never match, and hence the update fails. The
            issue will affect all queries, not just those from
            Connector/J.
          </p><p>
            To prevent this issue, use a primary key that does not use
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>. If you have to use a
            floating point column in your primary key, use
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">DOUBLE</code></a> or
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/fixed-point-types.html" target="_top"><code class="literal">DECIMAL</code></a> types in place of
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>.
          </p><p><a name="qandaitem-15-1-11"></a><span class="bold"><strong>15.11: </strong></span><span class="bold"><strong>
            You get an
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/error-messages-server.html#error_er_net_packet_too_large" target="_top"><code class="literal">ER_NET_PACKET_TOO_LARGE</code></a>
            exception, even though the binary blob size you want to
            insert using JDBC is safely below the
            <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html#sysvar_max_allowed_packet" target="_top"><code class="literal">max_allowed_packet</code></a> size.
          </strong></span></p><p>
            This is because the <code class="literal">hexEscapeBlock()</code>
            method in
            <code class="literal">com.mysql.jdbc.PreparedStatement.streamToBytes()</code>
            may almost double the size of your data.
          </p><p><a name="qandaitem-15-1-12"></a><span class="bold"><strong>15.12: </strong></span><span class="bold"><strong>
            What should you do if you receive error messages similar to
            the following: <span class="quote">“<span class="quote">Communications link failure – Last
            packet sent to the server was X ms ago</span>”</span>?
          </strong></span></p><p>
            Generally speaking, this error suggests that the network
            connection has been closed. There can be several root
            causes:
          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
                Firewalls or routers may clamp down on idle connections
                (the MySQL client/server protocol does not ping).
              </p></li><li class="listitem"><p>
                The MySQL Server may be closing idle connections that
                exceed the <code class="literal">wait_timeout</code> or
                <code class="literal">interactive_timeout</code> threshold.
              </p></li></ul></div><p>
            To help troubleshoot these issues, the following tips can be
            used. If a recent (5.1.13+) version of Connector/J is used,
            you will see an improved level of information compared to
            earlier versions. Older versions simply display the last
            time a packet was sent to the server, which is frequently 0
            ms ago. This is of limited use, as it may be that a packet
            was just sent, while a packet from the server has not been
            received for several hours. Knowing the period of time since
            Connector/J last received a packet from the server is useful
            information, so if this is not displayed in your exception
            message, it is recommended that you update Connector/J.
          </p><p>
            Further, if the time a packet was last sent/received exceeds
            the <code class="literal">wait_timeout</code> or
            <code class="literal">interactive_timeout</code> threshold, this is
            noted in the exception message.
          </p><p>
            Although network connections can be volatile, the following
            can be helpful in avoiding problems:
          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
                Ensure connections are valid when used from the
                connection pool. Use a query that starts with
                <code class="literal">/* ping */</code> to execute a lightweight
                ping instead of full query. Note, the syntax of the ping
                needs to be exactly as specified here.
              </p></li><li class="listitem"><p>
                Minimize the duration a connection object is left idle
                while other application logic is executed.
              </p></li><li class="listitem"><p>
                Explicitly validate the connection before using it if
                the connection has been left idle for an extended period
                of time.
              </p></li><li class="listitem"><p>
                Ensure that <code class="literal">wait_timeout</code> and
                <code class="literal">interactive_timeout</code> are set
                sufficiently high.
              </p></li><li class="listitem"><p>
                Ensure that <code class="literal">tcpKeepalive</code> is enabled.
              </p></li><li class="listitem"><p>
                Ensure that any configurable firewall or router timeout
                settings allow for the maximum expected connection idle
                time.
              </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
              Do not expect to be able to reuse a connection without
              problems, if it has being lying idle for a period. If a
              connection is to be reused after being idle for any length
              of time, ensure that you explicitly test it before reusing
              it.
            </p></div><p><a name="qandaitem-15-1-13"></a><span class="bold"><strong>15.13: </strong></span><span class="bold"><strong>
            Why does Connector/J not reconnect to MySQL and re-issue the
            statement after a communication failure, instead of throwing
            an Exception, even though I use the
            <code class="literal">autoReconnect</code> connection string option?
          </strong></span></p><p>
            There are several reasons for this. The first is
            transactional integrity. The MySQL Reference Manual states
            that <span class="quote">“<span class="quote">there is no safe method of reconnecting to the
            MySQL server without risking some corruption of the
            connection state or database state information</span>”</span>.
            Consider the following series of statements for example:
          </p><pre class="programlisting">

conn.createStatement().execute(
  "UPDATE checking_account SET balance = balance - 1000.00 WHERE customer='Smith'");
conn.createStatement().execute(
  "UPDATE savings_account SET balance = balance + 1000.00 WHERE customer='Smith'");
conn.commit();

</pre><p>
            Consider the case where the connection to the server fails
            after the <code class="literal">UPDATE</code> to
            <code class="literal">checking_account</code>. If no exception is
            thrown, and the application never learns about the problem,
            it will continue executing. However, the server did not
            commit the first transaction in this case, so that will get
            rolled back. But execution continues with the next
            transaction, and increases the
            <code class="literal">savings_account</code> balance by 1000. The
            application did not receive an exception, so it continued
            regardless, eventually committing the second transaction, as
            the commit only applies to the changes made in the new
            connection. Rather than a transfer taking place, a deposit
            was made in this example.
          </p><p>
            Note that running with <code class="literal">autocommit</code> enabled
            does not solve this problem. When Connector/J encounters a
            communication problem, there is no means to determine
            whether the server processed the currently executing
            statement or not. The following theoretical states are
            equally possible:
          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
                The server never received the statement, and therefore
                no related processing occurred on the server.
              </p></li><li class="listitem"><p>
                The server received the statement, executed it in full,
                but the response was not received by the client.
              </p></li></ul></div><p>
            If you are running with <code class="literal">autocommit</code>
            enabled, it is not possible to guarantee the state of data
            on the server when a communication exception is encountered.
            The statement may have reached the server, or it may not.
            All you know is that communication failed at some point,
            before the client received confirmation (or data) from the
            server. This does not only affect
            <code class="literal">autocommit</code> statements though. If the
            communication problem occurred during
            <code class="literal">Connection.commit()</code>, the question arises
            of whether the transaction was committed on the server
            before the communication failed, or whether the server
            received the commit request at all.
          </p><p>
            The second reason for the generation of exceptions is that
            transaction-scoped contextual data may be vulnerable, for
            example:
          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
                Temporary tables.
              </p></li><li class="listitem"><p>
                User-defined variables.
              </p></li><li class="listitem"><p>
                Server-side prepared statements.
              </p></li></ul></div><p>
            These items are lost when a connection fails, and if the
            connection silently reconnects without generating an
            exception, this could be detrimental to the correct
            execution of your application.
          </p><p>
            In summary, communication errors generate conditions that
            may well be unsafe for Connector/J to simply ignore by
            silently reconnecting. It is necessary for the application
            to be notified. It is then for the application developer to
            decide how to proceed in the event of connection errors and
            failures.
          </p><p><a name="qandaitem-15-1-14"></a><span class="bold"><strong>15.14: </strong></span><span class="bold"><strong>
            How can I use 3-byte UTF8 with Connector/J?
          </strong></span></p><p>
            To use 3-byte UTF8 with Connector/J set
            <code class="literal">characterEncoding=utf8</code> and set
            <code class="literal">useUnicode=true</code> in the connection string.
          </p><p><a name="qandaitem-15-1-15"></a><span class="bold"><strong>15.15: </strong></span><span class="bold"><strong>
            How can I use 4-byte UTF8, <code class="literal">utf8mb4</code> with
            Connector/J?
          </strong></span></p><p>
            To use 4-byte UTF8 with Connector/J configure the MySQL
            server with <code class="literal">character_set_server=utf8mb4</code>.
            Connector/J will then use that setting as long as
            <code class="literal">characterEncoding</code> has not been set in the
            connection string. This is equivalent to autodetection of
            the character set.
          </p><p><a name="qandaitem-15-1-16"></a><span class="bold"><strong>15.16: </strong></span><span class="bold"><strong>
            Using <code class="literal">useServerPrepStmts=false</code> and
            certain character encodings can lead to corruption when
            inserting BLOBs. How can this be avoided?
          </strong></span></p><p>
            When using certain character encodings, such as SJIS, CP932,
            and BIG5, it is possible that BLOB data contains characters
            that can be interpreted as control characters, for example,
            backslash, '\'. This can lead to corrupted data when
            inserting BLOBs into the database. There are two things that
            need to be done to avoid this:
          </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
                Set the connection string option
                <code class="literal">useServerPrepStmts</code> to
                <code class="literal">true</code>.
              </p></li><li class="listitem"><p>
                Set <code class="literal">SQL_MODE</code> to
                <code class="literal">NO_BACKSLASH_ESCAPES</code>.
              </p></li></ol></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-known-issues-limitations"></a>Chapter 16 Known Issues and Limitations</h1></div></div></div><a class="indexterm" name="idm140410756831568"></a><a class="indexterm" name="idm140410756830080"></a><a class="indexterm" name="idm140410756828592"></a><a class="indexterm" name="idm140410756827104"></a><a class="indexterm" name="idm140410756825616"></a><p>
      The following are some known issues and limitations for MySQL
      Connector/J:
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          When Connector/J retrieves timestamps for a daylight saving
          time (DST) switch day using the
          <code class="function">getTimeStamp()</code> method on the result set,
          some of the returned values might be wrong. The errors can be
          avoided by using the following connection options when
          connecting to a database:

</p><pre class="programlisting">
        useTimezone=true
        useLegacyDatetimeCode=false
        serverTimezone=UTC
      </pre><p>
        </p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-support"></a>Chapter 17 Connector/J Support</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-support-community">17.1 Connector/J Community Support</a></span></dt><dt><span class="section"><a href="#connector-j-support-bug-report">17.2 How to Report Connector/J Bugs or Problems</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-support-community"></a>17.1 Connector/J Community Support</h2></div></div></div><p>
        Oracle provides assistance to the user community by means of its
        mailing lists. For Connector/J related issues, you can get help
        from experienced users by using the MySQL and Java mailing list.
        Archives and subscription information is available online at
        <a class="ulink" href="http://lists.mysql.com/java" target="_top">http://lists.mysql.com/java</a>.
      </p><p>
        For information about subscribing to MySQL mailing lists or to
        browse list archives, visit
        <a class="ulink" href="http://lists.mysql.com/" target="_top">http://lists.mysql.com/</a>. See
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/mailing-lists.html" target="_top">MySQL Mailing Lists</a>.
      </p><p>
        Community support from experienced users is also available
        through the <a class="ulink" href="http://forums.mysql.com/list.php?39" target="_top">JDBC
        Forum</a>. You may also find help from other users in the
        other MySQL Forums, located at
        <a class="ulink" href="http://forums.mysql.com" target="_top">http://forums.mysql.com</a>. See
        <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/forums.html" target="_top">MySQL Community Support at the MySQL Forums</a>.
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-support-bug-report"></a>17.2 How to Report Connector/J Bugs or Problems</h2></div></div></div><a class="indexterm" name="idm140410756811312"></a><p>
        The normal place to report bugs is
        <a class="ulink" href="http://bugs.mysql.com/" target="_top">http://bugs.mysql.com/</a>, which is the address for
        our bugs database. This database is public, and can be browsed
        and searched by anyone. If you log in to the system, you will
        also be able to enter new reports.
      </p><p>
        If you find a sensitive security bug in MySQL Server, please let
        us know immediately by sending an email message to
        <code class="email">&lt;<a class="email" href="mailto:secalert_us@oracle.com">secalert_us@oracle.com</a>&gt;</code>. Exception: Support
        customers should report all problems, including security bugs,
        to Oracle Support at <a class="ulink" href="http://support.oracle.com/" target="_top">http://support.oracle.com/</a>.
      </p><p>
        Writing a good bug report takes patience, but doing it right the
        first time saves time both for us and for yourself. A good bug
        report, containing a full test case for the bug, makes it very
        likely that we will fix the bug in the next release.
      </p><p>
        This section will help you write your report correctly so that
        you do not waste your time doing things that may not help us
        much or at all.
      </p><p>
        If you have a repeatable bug report, please report it to the
        bugs database at <a class="ulink" href="http://bugs.mysql.com/" target="_top">http://bugs.mysql.com/</a>. Any bug
        that we are able to repeat has a high chance of being fixed in
        the next MySQL release.
      </p><p>
        To report other problems, you can use one of the MySQL mailing
        lists.
      </p><p>
        Remember that it is possible for us to respond to a message
        containing too much information, but not to one containing too
        little. People often omit facts because they think they know the
        cause of a problem and assume that some details do not matter.
      </p><p>
        A good principle is this: If you are in doubt about stating
        something, state it. It is faster and less troublesome to write
        a couple more lines in your report than to wait longer for the
        answer if we must ask you to provide information that was
        missing from the initial report.
      </p><p>
        The most common errors made in bug reports are (a) not including
        the version number of Connector/J or MySQL used, and (b) not
        fully describing the platform on which Connector/J is installed
        (including the JVM version, and the platform type and version
        number that MySQL itself is installed on).
      </p><p>
        This is highly relevant information, and in 99 cases out of 100,
        the bug report is useless without it. Very often we get
        questions like, <span class="quote">“<span class="quote">Why doesn't this work for me?</span>”</span>
        Then we find that the feature requested wasn't implemented in
        that MySQL version, or that a bug described in a report has
        already been fixed in newer MySQL versions.
      </p><p>
        Sometimes the error is platform-dependent; in such cases, it is
        next to impossible for us to fix anything without knowing the
        operating system and the version number of the platform.
      </p><p>
        If at all possible, create a repeatable, standalone testcase
        that doesn't involve any third-party classes.
      </p><p>
        To streamline this process, we ship a base class for testcases
        with Connector/J, named
        '<code class="classname">com.mysql.jdbc.util.BaseBugReport</code>'. To
        create a testcase for Connector/J using this class, create your
        own class that inherits from
        <code class="classname">com.mysql.jdbc.util.BaseBugReport</code> and
        override the methods <code class="function">setUp()</code>,
        <code class="function">tearDown()</code> and
        <code class="function">runTest()</code>.
      </p><p>
        In the <code class="function">setUp()</code> method, create code that
        creates your tables, and populates them with any data needed to
        demonstrate the bug.
      </p><p>
        In the <code class="function">runTest()</code> method, create code that
        demonstrates the bug using the tables and data you created in
        the <code class="literal">setUp</code> method.
      </p><p>
        In the <code class="function">tearDown()</code> method, drop any tables
        you created in the <code class="function">setUp()</code> method.
      </p><p>
        In any of the above three methods, use one of the variants of
        the <code class="function">getConnection()</code> method to create a JDBC
        connection to MySQL:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="function">getConnection()</code> - Provides a connection
            to the JDBC URL specified in <code class="function">getUrl()</code>.
            If a connection already exists, that connection is returned,
            otherwise a new connection is created.
          </p></li><li class="listitem"><p>
            <code class="function">getNewConnection()</code> - Use this if you
            need to get a new connection for your bug report (that is,
            there is more than one connection involved).
          </p></li><li class="listitem"><p>
            <code class="function">getConnection(String url)</code> - Returns a
            connection using the given URL.
          </p></li><li class="listitem"><p>
            <code class="function">getConnection(String url, Properties
            props)</code> - Returns a connection using the given URL
            and properties.
          </p></li></ul></div><p>
        If you need to use a JDBC URL that is different from
        'jdbc:mysql:///test', override the method
        <code class="function">getUrl()</code> as well.
      </p><p>
        Use the <code class="function">assertTrue(boolean expression)</code> and
        <code class="function">assertTrue(String failureMessage, boolean
        expression)</code> methods to create conditions that must be
        met in your testcase demonstrating the behavior you are
        expecting (vs. the behavior you are observing, which is why you
        are most likely filing a bug report).
      </p><p>
        Finally, create a <code class="function">main()</code> method that
        creates a new instance of your testcase, and calls the
        <code class="literal">run</code> method:
      </p><pre class="programlisting">
public static void main(String[] args) throws Exception {
      new MyBugReport().run();
 }
</pre><p>
        Once you have finished your testcase, and have verified that it
        demonstrates the bug you are reporting, upload it with your bug
        report to <a class="ulink" href="http://bugs.mysql.com/" target="_top">http://bugs.mysql.com/</a>.
      </p></div></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-third-party-licenses"></a>Appendix A Licenses for Third-Party Components</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#license-ant-contrib">A.1 Ant-Contrib License</a></span></dt><dt><span class="section"><a href="#license-c3p0-0-91">A.2 c3p0 JDBC Library License</a></span></dt><dt><span class="section"><a href="#license-gnu-lgpl-2-1">A.3 GNU Lesser General Public License Version 2.1, February 1999</a></span></dt><dt><span class="section"><a href="#license-jboss-common-jdbc-wrapper">A.4 jboss-common-jdbc-wrapper.jar License</a></span></dt><dt><span class="section"><a href="#license-nanoxml">A.5 NanoXML License</a></span></dt><dt><span class="section"><a href="#license-rox-jar">A.6 rox.jar License</a></span></dt><dt><span class="section"><a href="#license-slf4j">A.7 Simple Logging Facade for Java (SLF4J) License</a></span></dt><dt><span class="section"><a href="#license-unicode-data-files">A.8 Unicode Data Files</a></span></dt></dl></div><h2><a name="idm140410756773376"></a>MySQL Connector/J 5.1</h2><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="#license-ant-contrib" title="A.1 Ant-Contrib License">Section A.1, “Ant-Contrib License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-c3p0-0-91" title="A.2 c3p0 JDBC Library License">Section A.2, “c3p0 JDBC Library License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-gnu-lgpl-2-1" title="A.3 GNU Lesser General Public License Version 2.1, February 1999">Section A.3, “GNU Lesser General Public License Version 2.1, February 1999”</a></p></li><li class="listitem"><p><a class="xref" href="#license-jboss-common-jdbc-wrapper" title="A.4 jboss-common-jdbc-wrapper.jar License">Section A.4, “jboss-common-jdbc-wrapper.jar License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-nanoxml" title="A.5 NanoXML License">Section A.5, “NanoXML License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-rox-jar" title="A.6 rox.jar License">Section A.6, “rox.jar License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-slf4j" title="A.7 Simple Logging Facade for Java (SLF4J) License">Section A.7, “Simple Logging Facade for Java (SLF4J) License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-unicode-data-files" title="A.8 Unicode Data Files">Section A.8, “Unicode Data Files”</a></p></li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-ant-contrib"></a>A.1 Ant-Contrib License</h2></div></div></div><p>
    The following software may be included in this product up to version
    5.1.26: Ant-Contrib
  </p><pre class="programlisting">
Ant-Contrib
Copyright (c) 2001-2003 Ant-Contrib project. All rights reserved.
Licensed under the Apache 1.1 License Agreement, a copy of which is reproduced below.

The Apache Software License, Version 1.1

Copyright (c) 2001-2003 Ant-Contrib project.  All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:

 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.

 3. The end-user documentation included with the redistribution, if
    any, must include the following acknowlegement:
       "This product includes software developed by the
        Ant-Contrib project (http://sourceforge.net/projects/ant-contrib)."
    Alternately, this acknowlegement may appear in the software itself,
    if and wherever such third-party acknowlegements normally appear.

 4. The name Ant-Contrib must not be used to endorse or promote
    products derived from this software without prior written
    permission. For written permission, please contact
    ant-contrib-developers@lists.sourceforge.net.

 5. Products derived from this software may not be called "Ant-Contrib"
    nor may "Ant-Contrib" appear in their names without prior written
    permission of the Ant-Contrib project.

 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED.  IN NO EVENT SHALL THE ANT-CONTRIB PROJECT OR ITS
 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGE.
</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-c3p0-0-91"></a>A.2 c3p0 JDBC Library License</h2></div></div></div><p>
    You are receiving a copy of <code class="filename">c3p0-0.9.1-pre6.jar</code>
    in both source and object code in the following
    <code class="filename">/src/lib/c3p0-0.9.1-pre6.jar</code>. The terms of the
    Oracle license do NOT apply to
    <code class="filename">c3p0-0.9.1-pre6.jar</code>; it is licensed under the
    following license, separately from the Oracle programs you receive.
    If you do not wish to install this library, you may remove the file
    <code class="filename">/src/lib/c3p0-0.9.1-pre6.jar</code>, but the Oracle
    program might not operate properly or at all without the library.
  </p><p>
    This component is licensed under
    <a class="xref" href="#license-gnu-lgpl-2-1" title="A.3 GNU Lesser General Public License Version 2.1, February 1999">Section A.3, “GNU Lesser General Public License Version 2.1, February 1999”</a>.
  </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-gnu-lgpl-2-1"></a>A.3 GNU Lesser General Public License Version 2.1, February 1999</h2></div></div></div><pre class="programlisting">
The following applies to all products licensed under the
GNU Lesser General Public License, Version 2.1: You may
not use the identified files except in compliance with
the GNU Lesser General Public License, Version 2.1 (the
"License"). You may obtain a copy of the License at
http://www.gnu.org/licenses/lgpl-2.1.html. A copy of the
license is also reproduced below. Unless required by
applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
or implied. See the License for the specific language governing
permissions and limitations under the License.

                  GNU LESSER GENERAL PUBLIC LICENSE
                       Version 2.1, February 1999

 Copyright (C) 1991, 1999 Free Software Foundation, Inc.
 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

[This is the first released version of the Lesser GPL.  It also counts
 as the successor of the GNU Library Public License, version 2, hence
 the version number 2.1.]

                            Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.

  This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it.  You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.

  When we speak of free software, we are referring to freedom of use,
not price.  Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.

  To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights.  These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.

  For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you.  You must make sure that they, too, receive or can get the source
code.  If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it.  And you must show them these terms so they know their rights.

  We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.

  To protect each distributor, we want to make it very clear that
there is no warranty for the free library.  Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.

  Finally, software patents pose a constant threat to the existence of
any free program.  We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder.  Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.

  Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License.  This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License.  We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.

  When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library.  The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom.  The Lesser General
Public License permits more lax criteria for linking other code with
the library.

  We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License.  It also provides other free software developers Less
of an advantage over competing non-free programs.  These disadvantages
are the reason we use the ordinary General Public License for many
libraries.  However, the Lesser license provides advantages in certain
special circumstances.

  For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it
becomes a de-facto standard.  To achieve this, non-free programs
must be allowed to use the library.  A more frequent case is that
a free library does the same job as widely used non-free libraries.
In this case, there is little to gain by limiting the free library
to free software only, so we use the Lesser General Public License.

  In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software.  For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.

  Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.

  The precise terms and conditions for copying, distribution and
modification follow.  Pay close attention to the difference between a
"work based on the library" and a "work that uses the library".  The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.

                  GNU LESSER GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".

  A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.

  The "Library", below, refers to any such software library or work
which has been distributed under these terms.  A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language.  (Hereinafter, translation is
included without limitation in the term "modification".)

  "Source code" for a work means the preferred form of the work for
making modifications to it.  For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control
compilation and installation of the library.

  Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it).  Whether that is true depends on what the Library does
and what the program that uses the Library does.

  1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.

  You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.

  2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) The modified work must itself be a software library.

    b) You must cause the files modified to carry prominent notices
    stating that you changed the files and the date of any change.

    c) You must cause the whole of the work to be licensed at no
    charge to all third parties under the terms of this License.

    d) If a facility in the modified Library refers to a function or a
    table of data to be supplied by an application program that uses
    the facility, other than as an argument passed when the facility
    is invoked, then you must make a good faith effort to ensure that,
    in the event an application does not supply such function or
    table, the facility still operates, and performs whatever part of
    its purpose remains meaningful.

    (For example, a function in a library to compute square roots has
    a purpose that is entirely well-defined independent of the
    application.  Therefore, Subsection 2d requires that any
    application-supplied function or table used by this function must
    be optional: if the application does not supply it, the square
    root function must still compute square roots.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.

In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library.  To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License.  (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.)  Do not make any other change in
these notices.

  Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.

  This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.

  4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.

  If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.

  5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library".  Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.

  However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library".  The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.

  When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library.  The
threshold for this to be true is not precisely defined by law.

  If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work.  (Executables containing this object code plus portions of the
Library will still fall under Section 6.)

  Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.

  6. As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.

  You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License.  You must supply a copy of this License.  If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License.  Also, you must do one
of these things:

    a) Accompany the work with the complete corresponding
    machine-readable source code for the Library including whatever
    changes were used in the work (which must be distributed under
    Sections 1 and 2 above); and, if the work is an executable linked
    with the Library, with the complete machine-readable "work that
    uses the Library", as object code and/or source code, so that the
    user can modify the Library and then relink to produce a modified
    executable containing the modified Library.  (It is understood
    that the user who changes the contents of definitions files in the
    Library will not necessarily be able to recompile the application
    to use the modified definitions.)

    b) Use a suitable shared library mechanism for linking with the
    Library.  A suitable mechanism is one that (1) uses at run time a
    copy of the library already present on the user's computer system,
    rather than copying library functions into the executable, and (2)
    will operate properly with a modified version of the library, if
    the user installs one, as long as the modified version is
    interface-compatible with the version that the work was made with.

    c) Accompany the work with a written offer, valid for at
    least three years, to give the same user the materials
    specified in Subsection 6a, above, for a charge no more
    than the cost of performing this distribution.

    d) If distribution of the work is made by offering access to copy
    from a designated place, offer equivalent access to copy the above
    specified materials from the same place.

    e) Verify that the user has already received a copy of these
    materials or that you have already sent this user a copy.

  For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it.  However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.

  It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system.  Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.

  7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:

    a) Accompany the combined library with a copy of the same work
    based on the Library, uncombined with any other library
    facilities.  This must be distributed under the terms of the
    Sections above.

    b) Give prominent notice with the combined library of the fact
    that part of it is a work based on the Library, and explaining
    where to find the accompanying uncombined form of the same work.

  8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License.  Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License.  However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.

  9. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Library or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.

  10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.

  11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all.  For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended
to apply, and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

  13. The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number.  If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation.  If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.

  14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission.  For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this.  Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.

                            NO WARRANTY

  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.

                     END OF TERMS AND CONDITIONS

           How to Apply These Terms to Your New Libraries

  If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change.  You can do so by permitting
redistribution under these terms (or, alternatively, under the terms
of the ordinary General Public License).

  To apply these terms, attach the following notices to the library.
It is safest to attach them to the start of each source file to most
effectively convey the exclusion of warranty; and each file should
have at least the "copyright" line and a pointer to where the full
notice is found.

    &lt;one line to give the library's name and a brief idea of what it does.&gt;
    Copyright (C) &lt;year&gt;  &lt;name of author&gt;

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301  USA

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the
  library `Frob' (a library for tweaking knobs) written by James
  Random Hacker.

  &lt;signature of Ty Coon&gt;, 1 April 1990
  Ty Coon, President of Vice

That's all there is to it!
</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-jboss-common-jdbc-wrapper"></a>A.4 jboss-common-jdbc-wrapper.jar License</h2></div></div></div><p>
    You are receiving a copy of
    <code class="filename">jboss-common-jdbc-wrapper.jar</code> in both source
    and object code in the following
    <code class="filename">/src/lib/jboss-common-jdbc-wrapper.jar</code>. The
    terms of the Oracle license do NOT apply to
    <code class="filename">jboss-common-jdbc-wrapper.jar</code>; it is licensed
    under the following license, separately from the Oracle programs you
    receive. If you do not wish to install this library, you may remove
    the file
    <code class="filename">/src/lib/jboss-common-jdbc-wrapper.jar</code>, but the
    Oracle program might not operate properly or at all without the
    library.
  </p><p>
    This component is licensed under
    <a class="xref" href="#license-gnu-lgpl-2-1" title="A.3 GNU Lesser General Public License Version 2.1, February 1999">Section A.3, “GNU Lesser General Public License Version 2.1, February 1999”</a>.
  </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-nanoxml"></a>A.5 NanoXML License</h2></div></div></div><p>
    The following software may be included in this product:
  </p><p>
    NanoXML
  </p><pre class="programlisting">
 * Copyright (C) 2000-2002 Marc De Scheemaecker, All Rights Reserved.
 *
 * This software is provided 'as-is', without any express or implied warranty.
 * In no event will the authors be held liable for any damages arising from the
 * use of this software.
 *
 * Permission is granted to anyone to use this software for any purpose,
 * including commercial applications, and to alter it and redistribute it
 * freely, subject to the following restrictions:
 *
 *  1. The origin of this software must not be misrepresented; you must not
 *     claim that you wrote the original software. If you use this software in
 *     a product, an acknowledgment in the product documentation would be
 *     appreciated but is not required.
 *
 *  2. Altered source versions must be plainly marked as such, and must not be
 *     misrepresented as being the original software.
 *
 *  3. This notice may not be removed or altered from any source distribution.
 *
</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-rox-jar"></a>A.6 rox.jar License</h2></div></div></div><p>
    The following software may be included in this product:
  </p><p>
    rox.jar
  </p><pre class="programlisting">
Copyright (c) 2006, James Greenfield
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice, this
      list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
    * Neither the name of the &lt;ORGANIZATION&gt; nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 </pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-slf4j"></a>A.7 Simple Logging Facade for Java (SLF4J) License</h2></div></div></div><p>
    The following software may be included in this product:
  </p><pre class="programlisting">
Simple Logging Facade for Java (SLF4J)

Copyright (c) 2004-2008 QOS.ch
All rights reserved.

Permission is hereby granted, free of charge,
to any person obtaining a copy of this software
and associated documentation files (the "Software"),
to deal in the Software without restriction, including
without limitation the rights to use, copy, modify,
merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom
the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice
shall be included in all copies or substantial portions
of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY
OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-unicode-data-files"></a>A.8 Unicode Data Files</h2></div></div></div><p>
    The following software may be included in this product:
  </p><p>
    Unicode Data Files
  </p><pre class="programlisting">
COPYRIGHT AND PERMISSION NOTICE

Copyright © 1991-2014 Unicode, Inc. All rights reserved. Distributed under
the Terms of Use in http://www.unicode.org/copyright.html.

Permission is hereby granted, free of charge, to any person obtaining a copy
of the Unicode data files and any associated documentation (the "Data Files")
or Unicode software and any associated documentation (the "Software") to deal
in the Data Files or Software without restriction, including without
limitation the rights to use, copy, modify, merge, publish, distribute,
and/or sell copies of the Data Files or Software, and to permit persons to
whom the Data Files or Software are furnished to do so, provided that (a) the
above copyright notice(s) and this permission notice appear with all copies
of the Data Files or Software, (b) both the above copyright notice(s) and
this permission notice appear in associated documentation, and (c) there is
clear notice in each modified Data File or in the Software as well as in the
documentation associated with the Data File(s) or Software that the data or
software has been modified.

THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS
INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR
CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
DATA OR
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE
DATA FILES OR SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not
be used in advertising or otherwise to promote the sale, use or other
dealings in these Data Files or Software without prior written authorization
of the copyright holder.
</pre></div></div></div><div class="copyright-footer"></div></body></html>
